Errors

Every failure returns the same envelope, with the right HTTP status:

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  }
}

code is a stable machine string - branch on it, not on the human message. details is present only on a few errors with extra structure (see below). It is omitted otherwise, never null.

Codes

Status	`code`	When
400	`invalid_request`	Malformed parameters or JSON body (e.g. a bad uuid, an empty triage body).
401	`unauthorized`	A missing key on a protected endpoint, or an invalid, revoked, or expired key on any endpoint. A bad key never falls back to a lesser access level.
402	`payment_required`	A credit-spending action was blocked: the key hit its spend cap (`spend_cap_reached`) or the team is out of credits (`out_of_credits`). Branch on `details.reason`.
403	`forbidden`	A limit or guardrail: the plan’s watchlist product cap (`product_limit_reached`), or a credit tool called with an API key that has no spend cap (`spend_cap_required`).
404	`not_found`	Unknown resource id (or a product/opportunity not on your team).
429	`rate_limited`	Rate limit exceeded.
500	`internal_error`	Something went wrong on our side.
503	`internal_error`	A dependency is unavailable (the database, or report generation). On a credit action, the message says whether a credit was charged. Retry later.

`details` payloads

Some errors carry structured details: 403 product limit reached (follow a product past your plan cap):

{
  "code": "forbidden",
  "message": "Product limit reached for your plan",
  "details": { "reason": "product_limit_reached", "limit": 5, "current": 5, "upgrade_required": true }
}

403 spend cap required (a credit tool on a credential with no spend budget). For API keys, the spend cap is set when the key is created and cannot be added later: create a new key with a spend cap under Settings → API keys. OAuth connections can spend with no limit, so they don’t get this error.

{
  "code": "forbidden",
  "message": "This API key has no spend cap. Create a new key with a spend cap under Settings > API keys to enable credit-spending tools.",
  "details": { "reason": "spend_cap_required" }
}

402 spend cap reached (the credential’s rolling 30-day budget would be exceeded):

{
  "code": "payment_required",
  "message": "API key spend cap reached",
  "details": { "reason": "spend_cap_reached", "spend_cap": 100, "spend_used": 100, "spend_remaining": 0, "credits_required": 1 }
}

402 out of credits (the team’s balance is too low):

{
  "code": "payment_required",
  "message": "Insufficient credits",
  "details": { "reason": "out_of_credits", "credits_required": 1, "credits_remaining": 0 }
}

429 rate limited:

{ "code": "rate_limited", "details": { "retry_after_seconds": 12, "limit": 60, "remaining": 0 } }

Handling

Check success first, then switch on error.code:

const res = await fetch(url, { headers });
const body = await res.json();
if (!body.success) {
  switch (body.error.code) {
    case "unauthorized": /* refresh/replace the key */ break;
    case "rate_limited": /* honor Retry-After, then retry */ break;
    case "not_found": /* handle missing resource */ break;
    default: /* surface error.message */
  }
}

Get started

MCP

Guides

Codes

`details` payloads

Handling

​Codes

​details payloads

​Handling

Codes

`details` payloads

Handling