Errors

Use the HTTP status to decide how to handle a failure, then error.code to identify the cause. Correct invalid requests, wait for rate limits, and reconcile uncertain writes before starting another operation. Standard errors use this JSON envelope:

{
  "error": {
    "type": "invalid_request_error",
    "code": "schema_not_found",
    "message": "Schema not found."
  }
}

A success body is { "data": ... }, plus a pagination block on list endpoints and an optional top-level warnings array of strings. An aborting event batch is an exception: HTTP 422 returns data.results, data.summary, and data.failedIndex, so the caller can see rollback results. Inspect that business-result envelope before applying the standard error parser.

The error object

Status codes

Common response statuses are listed below. Successful calls include 200, 201 when a record, segment, or webhook is created, and 202 on events.fire and broadcasts.send, so do not test for 200 alone.

Common codes

code is the value to branch on. This is a representative set; individual endpoints document their own codes. Any failure without a specific code returns code: null, so fall back to the status.

identifier_conflict reflects the contact identity cascade: userId, then email, then phone for contacts, and externalId for objects. Use records/upsert to create-or-update by identity instead of failing on a strict create.

Server errors

A 5xx means the request could not complete normally. Standard error responses use type: "api_error" and a generic message. Keep the status, code, operation key, and any returned operation identifier in your logs.

{
  "error": {
    "type": "api_error",
    "code": null,
    "message": "Internal server error."
  }
}

A read can usually be retried with bounded exponential backoff and jitter. For a write, the response alone may not establish whether the action took effect. On supported endpoints, retain the original Idempotency-Key and payload. A recorded error can be replayed, and an unresolved outcome requires investigation.

Rate limits

A 429 means admission was refused. Rate and backlog limits can recover after a delay; receipt or identity capacity exhaustion can require operational reconciliation. Rate-limit failures use rate_limit_exceeded; an idempotent operation that cannot yet be admitted can use idempotency_admission_busy. Respect Retry-After before repeating the request.

The header can be an HTTP date or a delay in seconds. Handle both, and use a fallback if it is absent or invalid:

function retryAfterMs(value, now = Date.now()) {
  if (!value) return 1000
  const seconds = Number(value)
  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000)
  const date = Date.parse(value)
  return Number.isFinite(date) ? Math.max(0, date - now) : 1000
}

const waitMs = retryAfterMs(response.headers.get('Retry-After'))
const delayWithJitter = waitMs + Math.random() * 250

Use that delay in a bounded retry loop. See rate limits for request budgets and batching.

Handling errors

Classify the outcome before retrying. These decisions apply whether you call the API directly or through a client library:

A successful HTTP status can still contain an operation-level failure. For example, templates.send can return 200 with data.status: "failed". Inspect the documented result fields as well as response.ok. Template failed also covers uncertain provider outcomes and retryable refusals; retain emailId and the operation key and reconcile before issuing a new send.