Errors

Every error response uses the RFC 7807 application/problem+json shape, so error handling is uniform across the whole API:

json

{
  "type": "about:blank",
  "title": "Forbidden",
  "status": 403,
  "detail": "missing scope 'orders:write' for 'orders.archive.place'"
}

Field	Meaning
`status`	The HTTP status code (mirrors the response status)
`title`	A short, stable human-readable summary of the error class
`detail`	A specific, contextual message about this error
`type`	A URI identifying the problem type (`about:blank` when the status is sufficient)

The error model is owned by the kernel, so every operation returns errors the same way — there is no per-endpoint error format to special-case.

Status codes

Code	Meaning	Typical cause
`400 Bad Request`	Malformed request	A structurally invalid body
`401 Unauthenticated`	No / invalid token	Missing or expired Bearer token
`403 Forbidden`	Insufficient scope or access	The principal lacks the operation’s scope, or isn’t a member of the target’s project/org
`404 Not Found`	Unknown resource or operation	A bad id, or a resource outside your organization (returned as 404, not 403, to avoid leaking existence)
`402 Payment Required`	Cannot charge	Insufficient credits, no/declined card, or a past-due account
`409 Conflict`	State conflict	An invalid state transition, or a concurrent change that lost the race
`410 Gone`	Expired / retired	An expired approval or a retention-expired asset
`422 Unprocessable Entity`	Input failed validation	The body parsed but failed the operation’s typed schema or a domain rule (e.g. invalid geometry)
`429 Too Many Requests`	Rate limited	Per-key rate limit or an egress/bandwidth limit
`500 Internal Server Error`	Server fault	An unexpected backend error

Validation errors

Because every operation has a typed input model, malformed inputs fail fast with 422 Unprocessable Entity before any side-effect runs — the wrong input never reaches the handler. The detail field describes which field failed and why.

Payment & spend errors

Spend operations (placing an order, topping up, creating a processing job) surface billing problems as 402 Payment Required:

Insufficient credits — top up, or enable auto top-up.
No / declined card — attach a payment method.
3-D Secure required — the response carries a client_secret so the client can complete the bank challenge, then retry.

Idempotent retries

Spend operations accept an Idempotency-Key header. If a request times out, retry it with the same key: a duplicate is detected and the original result is returned rather than charging or acting twice. This makes spend operations safe to retry on network failure.

A note on 403 vs 404

To avoid leaking the existence of resources across organizations, the platform returns 404 Not Found (not 403 Forbidden) when you reference a resource that exists but belongs to another organization. A 403 means you authenticated, but your scope or project membership doesn’t permit this action on a resource you can see.