Error Handling

The full list of error codes is in Developers → Errors.

Error response format

Every error has the same body:

{
  "statusCode": 400,
  "code": "VALIDATION_RULE_FAILED",
  "message": "Close date is required once a deal reaches Negotiation",
  "timestamp": "2026-10-01T09:30:00.000Z",
  "path": "/v1/opportunities/clx…",
  "requestId": "6f1c…"
}

Branch on code, not on message; messages are written for people and can change.
message is an array when a request fails several input validations at once:
{ "statusCode": 400, "message": ["email must be an email", "property nickname should not exist"], "…": "…" }
Quote requestId when you contact support.

Status codes

Status	Meaning	Retry?
`200`, `201`, `202`, `204`	Success (`202` for queued jobs such as bulk and metadata deploys)	—
`400`	Malformed or invalid request, or a business rule refused it	No. Fix the request
`401`	Missing, invalid, expired or revoked credentials	No. Fix the credential
`403`	Not allowed: scope, plan, Profile, IP allow-list, field-level security	No
`404`	Not found, or not visible to you (indistinguishable on purpose)	No
`409`	Conflict: an idempotency conflict or a state conflict	Depends on the code
`423`	The record is locked by a pending approval	After the approval completes
`429`	Rate limited	Yes, after `Retry-After` seconds
`500`	Unexpected error	Reads: yes, with backoff. Writes: only with an `Idempotency-Key`
`503`	Temporarily unavailable	Yes, after `Retry-After`

Handling errors

async function apiRequest(url, options) {
  const res = await fetch(url, options);
  if (res.ok) return res.status === 204 ? null : res.json();

  const error = await res.json();
  if (res.status === 429 || res.status === 503) {
    const wait = Number(res.headers.get('Retry-After') ?? 1);
    // wait `wait` seconds, then retry (writes only with an Idempotency-Key)
  }
  switch (error.code) {
    case 'API_KEY_EXPIRED':
      // rotate the key
      break;
    case 'VALIDATION_RULE_FAILED':
      // show error.message to the user
      break;
  }
  throw error;
}

Error response format

Status codes

Handling errors

On this page