Inbox Triage
Start free trial

Get started

Errors

Errors use HTTP status codes and the same JSON body on every route.

Error shape

Every /api error has a short snake_case code in error and a sentence in error_description. Branch on error, and show error_description to the person if you need to. A few errors add fields, such as approveUrl or heldBy.

Response409 
{
  "error": "inbox_paused",
  "error_description": "The inbox \"Work\" is paused. The person can resume it on the Inboxes page."
}

Status codes

StatusErrorMeaning
400 invalid_request, invalid_label, action_failed, draft_failed, bad_request Missing or invalid input, or the provider refused the change. Malformed JSON returns bad_request.
401 missing_api_key, invalid_api_key No API key, or a wrong or revoked one.
402 trial_expired, past_due, upgrade_required, approval_required The trial ended, or a failed payment is past its grace period. Also a plan change the person has to approve.
403 owner_session_required, email_not_verified, inbox_limit The call needs the signed-in person, a confirmed email, or a free inbox slot.
404 inbox_not_found, message_not_found, not_found No such inbox, message, or route.
409 inbox_paused, lease_busy, not_connected The inbox is paused, another agent holds the triage lease, or the inbox has no working credential.
413 payload_too_large JSON bodies are limited to 100 KB.
429 rate_limited Too many requests. Wait the number of seconds in Retry-After. See Limits.
500 internal_error No details are returned. Retry later.
503 storage_unavailable Storage is briefly unavailable. Retry later.

Failures that return 200

Sync, load older, and similar calls report provider failures as ok: false with an error string and HTTP 200. Check ok, not only the status.

MCP errors

MCP tool errors come back as a normal result with isError: true and a readable message. An expired trial or blocked payment still lets an agent connect and list tools, but every tool call returns a message to pass to the person. Too many requests to /mcp get HTTP 429 with Retry-After and a JSON-RPC error whose data.error is rate_limited.

OAuth errors

The /oauth/token, /oauth/revoke, and /oauth/register endpoints use the error codes from their RFCs, such as invalid_client and invalid_grant, in the same error and error_description fields.