Errors

Copied
Previous Next

The API uses standard HTTP status codes. Error responses may use a detail field (FastAPI default) or the structured schema below.

Error response body

Many endpoints return a structured error body:

Field Type Description
error string Error code (e.g. for programmatic handling)
message string Human-readable message
details object | null Optional extra context
request_id string | null Request ID for support/tracing

Some errors return a simple body: {"detail": "message"}. Always check the HTTP status code first.

HTTP status codes

Status Meaning Typical cause
400 Bad Request Invalid payload, invalid invitation token, validation failure
401 Unauthorized Missing or invalid API key, invalid/expired OIDC token, tenant not active
402 Payment Required Plan quota exceeded (e.g. max inboxes, items per month)
403 Forbidden Sender not allowed for inbox, invitation email mismatch, permission denied
404 Not Found Inbox, item, job, or delivery not found
409 Conflict Tenant slug already taken, job not cancellable, duplicate invite
413 Payload Too Large Request body or upload exceeds size limit
422 Unprocessable Entity Validation error on request body (e.g. missing required field)
429 Too Many Requests Rate limit exceeded; retry after delay (see Retry-After if present)
500 Internal Server Error Server error; retry with backoff

Quota exceeded (402)

When your account has reached a plan limit, the API returns 402 Payment Required. Typical cases:

  • Max inboxes — POST /v1/inboxes when you are already at your plan’s inbox limit.
  • Items per month — POST /v1/inboxes/{inbox_id}/items when you have reached your plan’s monthly item limit.

The response body includes a message indicating which limit was exceeded. Upgrade your plan or wait for the next billing period (for item quotas) to create more resources.

Authentication (401)

Common 401 cases:

  • Missing API key - Send Authorization: Bearer <key> or X-API-Key: <key>.
  • Invalid API key - Key not found, wrong value, or revoked. Create a new key in the dashboard (API keys).
  • Invalid OIDC token - Token expired, invalid signature, or missing claim.

Not found (404)

Resource IDs are UUIDs. A 404 means no resource exists for that ID in your tenant (or the path is wrong). Example messages: "Item {id} not found", "Inbox not found".

Validation (400, 422)

  • 400: Often a business-rule or format issue (e.g. invalid invitation token).
  • 422: Request body failed schema validation; the response may include field-level details.

Rate limits (429)

If you receive 429, back off and retry. The API may send a Retry-After header. The official SDKs retry with backoff and respect Retry-After when present.

Webhooks Schemas