Errors and troubleshooting

Every non-2xx response has the same envelope:

{
  "error": {
    "type": "...",
    "message": "human-readable explanation",
    "fields": { "field_name": "what's wrong" },
    "request_id": "req_01HZX2…"
  }
}

fields is present on validation errors and most processor errors. request_id is always present — quote it in support tickets and we can pull the matching switch log.

Status code reference

Status	Type	Typical cause	What to do
401	`authentication_error`	Token wrong, rotated, used in the wrong environment	Try `GET /ping`; rotate if needed
404	`not_found`	Wrong `username` or `conn_id`	Check the id — connection ids are `<merchant-id>-ACQ-<CODE>` (see Conventions)
409	`conflict`	Already exists (merchant username taken, already boarded onto this acquirer, etc.)	Check before create, or read the existing resource
422	`validation_error`	Your payload is wrong	Look at `fields` — it names the bad ones
422	`processor_error`	Upstream processor failed (unreachable, busy, or rejected for a reason the caller can't fix)	Read `message`. Retry the identical request after a back-off, or escalate

Processor errors in detail

processor_error happens when an upstream processor couldn't complete the request — typically during boarding. The processor was unreachable, busy, or rejected the request for a reason the caller can't fix. fields is empty; the message carries a processor-neutral reason.

{
  "error": {
    "type": "processor_error",
    "message": "a processor is temporarily unavailable",
    "fields": {},
    "request_id": "req_01HZX2…"
  }
}

Retry the identical request after a back-off, or escalate if it persists. Don't mutate the payload — the input was fine; the upstream wasn't.

When to contact Fat Zebra support

Any 5xx response (we don't expect these, but if you see one, send the request_id).
A processor_error whose message doesn't match anything in the acquirer's docs.
A 401 that persists after rotating the token.

Always include the request_id from the error response.