Skip to content

Error codes

Every 4xx and 5xx response, and every MCP tool error, has this shape:

{ "error": { "code": "SCREAMING_SNAKE", "message": "Human readable, safe to show", "details": { … } } }

The OAuth endpoints (/oauth/*, outside /api) use the OAuth format instead: { error, error_description }, with codes such as invalid_client, invalid_grant, invalid_request, invalid_target, invalid_redirect_uri, invalid_client_metadata, unsupported_grant_type, temporarily_unavailable.

Code Status What to do
UNAUTHENTICATED 401 Send Authorization: Bearer <key or token>
INVALID_API_KEY 401 The key is wrong, revoked or expired, or its agent archived. Stop and ask a person
INVALID_TOKEN 401 OAuth: refresh the access token, or connect again if the connection was revoked. On REST, use an API key
FORBIDDEN 403 The key lacks details.required (or a browser Origin was refused at /mcp). Do not retry
PLAN_LIMIT_REACHED 402 Free plan limit details.limit is at details.max. Do not retry or work around it; tell a person the message (it names details.upgradeUrl)
ACCOUNT_REQUIRED 400 MCP, multi-account connection: pass accountId from details.accounts
ACCOUNT_NOT_FOUND 400 (MCP) MCP, multi-account connection: that account is not in the connection
Code Status What to do
VALIDATION_FAILED 400 Fix each details.fields[] (field, reason, message, maybe allowed). Also malformed JSON (reason: INVALID_JSON)
FILTER_INVALID 400 Use a field or op from details.allowed
MATCH_KEY_MISSING 400 (upsert item) The item lacks the matchOn key. details.reason: FREE_MAIL_DOMAIN: skip that organization
PAYLOAD_TOO_LARGE 413 Bodies are at most 2 MB: split the batch
METHOD_NOT_ALLOWED 405 /mcp takes POST only
Code Status What to do
NOT_FOUND 404 Wrong id, or another account’s record (never distinguished)
DUPLICATE 409 Use details.existingId (details.field says which key), or upsert instead of create
AMBIGUOUS_MATCH 409 (upsert item) Several records carry that external ref; match by id
VERSION_CONFLICT 409 Re-read (details.current), re-apply, retry
RELATED_RECORD_NOT_FOUND 422 A linked id in the body (details.field, details.id) does not exist in this account
STAGE_NOT_FOUND 422 stageName unknown in that pipeline. Pick from details.allowed
STAGE_NOT_IN_PIPELINE 422 The stage belongs to another pipeline. Pick from details.allowed
PIPELINE_INVALID 422 Stage rules broken (≥ 1 open, exactly 1 won). See details.reason
PIPELINE_NOT_EMPTY 422 The pipeline has deals: archive it instead
DEFAULT_PIPELINE 422 The default pipeline cannot be deleted or archived
STAGE_NOT_EMPTY 422 Pass moveDealsTo
FIELD_IMMUTABLE 422 A custom field’s key, type and entityType never change: delete and define again
TOO_MANY_FIELDS 422 At most 50 active custom field definitions per record type
Code Status What to do
IDEMPOTENCY_IN_PROGRESS 409 The first request with this key is still running. Wait a second, retry with the same key
IDEMPOTENCY_KEY_REUSED 422 Same key, different request. A new request needs a new key
RATE_LIMITED 429 Wait Retry-After seconds (also details.retryAfterSeconds)
INTERNAL_ERROR 500 Our side. Retry later with the same idempotency key; quote X-Request-Id in feedback
NOT_READY 503 GET /api/ready only: the service is starting or the database is unreachable

Human-only routes (sign-in, invitations, billing) have their own codes (INVALID_CREDENTIALS, SESSION_EXPIRED, TOKEN_INVALID, EMAIL_IN_USE, ALREADY_MEMBER, LAST_OWNER, ALREADY_SUBSCRIBED, NO_BILLING_CUSTOMER, BILLING_UNAVAILABLE…); an agent key never reaches them.