Errors

When a request fails, the gateway returns a problem response with Content-Type: application/problem+json and a consistent shape. The HTTP status is what you branch on; the body explains the detail.

Problem shape

{
  "type": "https://errors.zeam.app/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The 'amount' field must be a positive decimal.",
  "instance": "/v1/quotes",
  "requestId": "01J8Z6K3QW9F2",
  "errors": [
    { "field": "amount", "message": "must be > 0" }
  ]
}

string

A stable URI identifying the error category, under https://errors.zeam.app/.

string

Short, human-readable summary of the category.

integer

The HTTP status code, repeated in the body.

string

A human-readable, actionable explanation of this specific failure.

string

The path that produced the error.

string

Mirrors the X-Request-Id response header. Quote it in support requests.

array

Field-level validation failures, when applicable. Each item has a field and a message.

Error catalogue

Status	`type` suffix	When it happens
`400`	`validation-error`	Malformed body or query parameters.
`401`	`unauthenticated`	Missing or invalid bearer token or `x-zeam-auth`. Generic by design.
`403`	`forbidden`	Authenticated, but not permitted for this action.
`404`	`not-found`	The wallet, transaction, or other resource does not exist.
`409`	`conflict`	The request conflicts with existing state, such as a duplicate webhook registration.
`412`	`precondition-required`	A required context header is missing, such as `x-association-id`.
`422`	`validation-error`	The body parsed but failed field validation; see `errors`.
`429`	`rate-limited`	Too many requests. Honor `Retry-After`. See rate limits.
`502`	`upstream-error`	A downstream service returned an unexpected error.
`504`	`upstream-timeout`	A downstream service timed out.
`500`	`internal-error`	An unexpected error in the gateway.

Handling guidance

Branch on the HTTP status, then read type for the specific category.
401 is intentionally generic and never says which credential failed. Re-authenticate and retry with valid credentials.
429, 502, 504 are transient. Retry with backoff; for 429, wait for Retry-After.
400, 422 are caused by the request. Fix the input using detail and errors, then retry.
412 means a required header is missing; add x-association-id and retry.
409 means the resource already exists; reconcile instead of recreating.
Always capture requestId so Zeam can trace the exact request.

Get started

Authentication

Access & environments

Webhooks

AI & developer tools

Platform

Problem shape

Error catalogue

Handling guidance

​Problem shape

​Error catalogue

​Handling guidance

Problem shape

Error catalogue

Handling guidance