Skip to main content
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" }
  ]
}
​
type
string
A stable URI identifying the error category, under https://errors.zeam.app/.
​
title
string
Short, human-readable summary of the category.
​
status
integer
The HTTP status code, repeated in the body.
​
detail
string
A human-readable, actionable explanation of this specific failure.
​
instance
string
The path that produced the error.
​
requestId
string
Mirrors the X-Request-Id response header. Quote it in support requests.
​
errors
array
Field-level validation failures, when applicable. Each item has a field and a message.

​
Error catalogue

Statustype suffixWhen it happens
400validation-errorMalformed body or query parameters.
401unauthenticatedMissing or invalid bearer token or x-zeam-auth. Generic by design.
403forbiddenAuthenticated, but not permitted for this action.
404not-foundThe wallet, intent, or other resource does not exist.
422validation-errorThe body parsed but failed field validation; see errors.
429rate-limitedToo many requests. Honor Retry-After. See rate limits.
502upstream-errorA downstream service returned an unexpected error.
504upstream-timeoutA downstream service timed out.
500internal-errorAn 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.
  • Always capture requestId so Zeam can trace the exact request.