Scopes and errors

Every public API operation requires one explicit scope. A valid credential without that scope receives 403 insufficient_scope; it is never silently upgraded to broader access.

Scope reference#

Use read scopes for reporting jobs. Add a write scope only when the integration performs that mutation. For example, a lead export normally needs sites:read and leads:read, not sites:write or agents:write.

Scope failures#

{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key does not grant the required scope.",
    "details": { "required": ["sites:write"] },
    "request_id": "6c0b2f2e-..."
  }
}

Add the missing scope to the key under Settings → Developer → Edit, or create a replacement key and update the server secret. Editing changes the key's name and scopes in place; its expiry and token stay the same. Keys issued through OAuth cannot be edited; reconnect the application to change what it was granted.

Error envelope#

All API errors use the same top-level shape:

type ApiError = {
  error: {
    code: string;
    message: string;
    details?: unknown;
    request_id: string;
  };
};

Branch on error.code, not the English message. Messages can improve without a version change. Log error.request_id and the x-request-id response header with the operation name, status, and retry attempt—but never log the authorization header or request secrets.

Status and code reference#

Resources outside the credential owner's account can return 404 instead of revealing whether another tenant's ID exists.

Validation details#

Field validation returns paths that can be shown next to your own form controls:

{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed.",
    "details": [
      { "path": "content.headline", "message": "String must contain at least 1 character(s)" }
    ],
    "request_id": "6c0b2f2e-..."
  }
}

Mutation bodies must be JSON objects. Arrays, empty bodies, form data, and JSON sent with a text content type are rejected.

Retry decisions#

• Retry 429 after the number of seconds in Retry-After.
• Retry 500 only for safe reads or writes protected by the same Idempotency-Key.
• Retry the in-progress idempotency 409 after its Retry-After: 2 header.
• Never retry 503 outcome_unknown blindly. Check the resource first; use a new idempotency key only after confirming the change did not happen.
• Do not retry 400, 401, 403, 404, 413, or a state conflict until the cause changes.

See Rate limits for backoff behavior and API reference for the required scope on each operation.