Errors

Anything but 2xx did nothing, unless noted. All responses are JSON, errors included.

Status codes

Status	Meaning	Body	Retry?
200	Retrieved, or existing intent (Idempotency)	{"data": {...}}	—
201	Created	{"data": {...}}	—
401	Bad or missing credentials	message or error (below)	No
403	Another application’s intent	{"message": "Unauthorized access to payment intent."}	No
404	Unknown uuid or path	{"message": "Not found."}	No
409	Rare create conflict	{"message": "Conflict creating payment intent."}	Yes, same merchant_reference
422	Validation failed	{"message": ..., "errors": {...}}	No
429	Over 300 a minute per organization	{"message": "Too Many Attempts."}	After Retry-After seconds
5xx	Fanak’s side	Varies	Yes, same merchant_reference

Retry network errors and 5xx with growing delays; the same merchant_reference never creates a second intent.

Authentication errors (401)

Body	Cause
{"message": "Unauthenticated."}	Access token missing, invalid or revoked.
{"error": "Missing X-API-Key header."}	No API key.
{"error": "Invalid API key or inactive application."}	Unknown key, another organization’s, or inactive application.

Validation errors (422)

errors maps each field (dotted when nested: metadata.order_id) to its messages.

{
  "message": "The merchant reference field is required. (and 3 more errors)",
  "errors": {
    "merchant_reference": ["The merchant reference field is required."],
    "amount": ["The amount field must be at least 1000."],
    "currency": ["The currency field is required."],
    "description": ["The description field is required."]
  }
}

Messages are English, for developers, and may change: branch on status and field names, and show customers your own text.

Coming later

A single error format.