Errors

Every failure has the same shape, whatever the endpoint:

{
  "error": {
    "code": "validation_failed",
    "message": "A required field is empty",
    "details": { "field": "budget", "reason": "field_required" },
    "request_id": "req_6f1c2b9e4d7a4c0e9b3f5a8d2e1c7b40"
  }
}

Branch on codes, not messagesCopy Anchor Link

message is written for humans and may change at any time. It often names the value in cause, and its wording is improved without notice. Never parse it.

Your code should branch on:

1. error.code, for the class of problem (and the HTTP status);
2. error.details.reason, for the exact rule that refused the call, when present.

const res = await fetch(url, { headers: { Authorization: `Bearer ${key}` } });
if (!res.ok) {
  const { error } = await res.json();
  if (error.code === "rate_limited") {
    // wait Retry-After seconds, then retry
  } else if (error.details?.reason === "scope_missing") {
    // ask for a key with error.details.required
  } else if (error.details?.reason === "plan_required") {
    // the agency's plan lacks error.details.feature
  }
}

Codes and reasons are part of the API contract: new ones can be added, existing ones are never renamed.

Error codesCopy Anchor Link

• 400 invalid_request: the request itself is malformed (an unknown query parameter, a filter or sort the resource does not support, invalid JSON, a body that is not an object, a bad Idempotency-Key). details lists what is accepted when that helps.
• 401 unauthorized: no key, an unknown key, or a revoked or expired key. See Authentication.
• 403 forbidden: the key is valid but may not do this. details.reason says why (missing scope, plan, suspended key…).
• 404 not_found: the resource, the record or the action does not exist for this agency. Records of other agencies are indistinguishable from records that do not exist.
• 409 conflict: the current state forbids the action, or an Idempotency-Key was reused (see Idempotency).
• 413 payload_too_large: the body is over 1 MiB; details.limit is the limit in bytes.
• 422 validation_failed: the request is well-formed but a value is refused.
• 429 rate_limited: too many requests, or the monthly quota is spent. Always comes with Retry-After. See Rate limits and quota.
• 500 server_error: a problem on our side. It is recorded automatically; retry later and quote the request_id if it persists.

Refusal reasonsCopy Anchor Link

When a business rule refuses a call, details.reason names it, next to the unchanged code. The table below lists every reason with its class and a short meaning.

Some reasons are documented with the feature they belong to rather than in this table: the 429 reasons (burst_limit, write_burst_limit, ip_limit, auth_failures, volume_budget, agency_quota_exhausted, user_quota_exhausted) in Rate limits and quota, the 409 reasons idempotency_key_conflict and idempotency_key_in_flight in Idempotency, and feature_disabled (a 404 for a collection that is switched off on the platform, with details.feature).

Common detailsCopy Anchor Link

details.fieldCopy Anchor Link

When a single field is at fault, details.field names it, as the key you sent (endAt, projectId, or the key of a custom field):

{
  "error": {
    "code": "validation_failed",
    "message": "Invalid input",
    "details": { "field": "endAt", "reason": "invalid_input" },
    "request_id": "req_…"
  }
}

When the body does not match the resource's schema at all (a wrong type, a missing required field, an unknown field), details is instead a list, one entry per problem:

{
  "error": {
    "code": "validation_failed",
    "message": "Invalid input: expected string, received undefined",
    "details": [
      { "field": "name", "message": "Invalid input: expected string, received undefined" }
    ],
    "request_id": "req_…"
  }
}

details.feature with plan_requiredCopy Anchor Link

A feature the agency's plan does not include is refused with 403 forbidden, details.reason: "plan_required", and details.feature, the id of the missing feature or add-on (for example chat, portal_branding, seo or rank_tracking). Use it to point the agency to the right upgrade instead of parsing the message.

{
  "error": {
    "code": "forbidden",
    "message": "The sitemap tool requires the Pro plan or above.",
    "details": { "feature": "seo", "reason": "plan_required" },
    "request_id": "req_…"
  }
}

details.max and details.count with limitsCopy Anchor Link

A refusal because a ceiling is reached (limit_reached and the more specific *_limit_reached reasons) carries details.max, the ceiling, and details.count, the current number, when it is known:

{
  "error": {
    "code": "validation_failed",
    "message": "This client already tracks 50 questions, the maximum. …",
    "details": { "max": 50, "count": 50, "reason": "limit_reached" },
    "request_id": "req_…"
  }
}

Accepted valuesCopy Anchor Link

A 400 about a query parameter lists what the resource accepts: accepted, filterable or sortable. A 403 scope_missing lists required and granted. See Requests and responses and Authentication.