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.