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 acquirer rejected the request	Read `message` — it carries the acquirer's reason. Fix and re-submit

Processor errors in detail

processor_error only happens on requests that touch an acquirer — most often boarding. The acquirer rejected the request synchronously and we're passing their reason back to you. fields may be empty; the message is the canonical signal.

{
  "error": {
    "type": "processor_error",
    "message": "NAB rejected the boarding request: invalid MID",
    "fields": { "mid": "must be 10 digits" },
    "request_id": "req_01HZX2…"
  }
}

Re-submit with the corrected payload. There is nothing to retry on the server side — a processor_error means the upstream definitively said no.

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.