Errors

Every error response on the public API uses the same JSON envelope, so an integration can write one parser that handles every failure mode. HTTP status carries the broad category; the body carries a stable machine-readable code, a human message, and an optional data object with structured context.

Error Envelope

Every error response carries the same shape, regardless of the HTTP status:

{
  "code": "not_admissible",
  "message": "The operation was refused",
  "data": { "reason": "CLIENT_NOT_VERIFIED", "source": "verification" }
}
  • code — stable, machine-readable identifier for the error. Use this in your branching logic.
  • message — human-readable description, suitable for logs or developer tooling. Not localized; not safe to surface to end users verbatim.
  • data — optional, documented context such as reason, admission source, legal document version, or retry_after_ms. Internal service fields are not generally exposed.

The OpenAPI JSON download includes the shared error response schemas under components.responses.

HTTP Status Mapping

The HTTP status tells you which kind of failure happened. The same status can carry different code values depending on the situation, but the high-level meaning is fixed:

Status Meaning Typical causes
400 Bad Request The request payload, query, or parameter shape is invalid. Missing required field, malformed JSON, bad enum value.
401 Unauthorized Authentication failed. Missing, expired, or invalid bearer token. POST /oauth/token refuses a bad client credential with 400 invalid_request instead.
403 Forbidden Authenticated, but not allowed to perform this operation in this scope. Capability not granted, scope outside granted authority.
404 Not Found The referenced resource does not exist or is not visible to the caller. Wrong id, resource in another tenant, resource retired.
409 Conflict The request conflicts with the current state of the resource. Idempotency-key mismatch, lifecycle precondition not met.
410 Gone The endpoint is retired. Use the documented replacement.
412 Precondition Failed The If-Match ETag did not match the current resource version. Concurrent update; re-read and retry.
422 Unprocessable Entity A valid request is not admissible. Verification, lifecycle, policy, or compliance gate refused it.
429 Too Many Requests A rate limit was exceeded. Use data.retry_after_ms when present; otherwise back off.
500 Internal Server Error An unexpected internal failure occurred. Inspect the error and retry only as appropriate for the operation.
502 Bad Gateway An upstream system the platform depends on returned an error. Dependency failure; preserve idempotency when retrying.
503 Service Unavailable Operation temporarily not available. Maintenance, load shedding; retry with backoff.

Rate limits currently come from upstream services; the edge does not send a Retry-After header. Both 500 and 503 can use temporarily_unavailable, so branch on HTTP status as well as the code.

For idempotency-related conflicts, see Idempotency And Concurrency.

Code Conventions

code values are stable strings. Common codes include unauthorized, invalid_request, and forbidden_capability_scope. Match the exact documented code and any data.reason refinement; do not derive codes from the human message.

How This Appears In The API

Response

401 application/json
{
  "code": "unauthorized",
  "message": "Token expired"
}

Response from POST /oauth/token

400 application/json
{
  "code": "invalid_request",
  "message": "invalid credentials",
  "data": {
    "reason": "missing_required_field"
  }
}

Response

400 application/json
{
  "code": "invalid_request",
  "message": "amount.value: Invalid input"
}

Response

412 application/json
{
  "code": "precondition_failed",
  "message": "etag mismatch",
  "data": {
    "reason": "etag_mismatch"
  }
}