Error Handling

API error codes, formats, and troubleshooting

HTTP Status Codes

Code	Meaning
`200`	Success
`201`	Created
`204`	Success — no body (deletions)
`400`	Bad request — check `detail`
`401`	Authentication failed — invalid or missing `X-API-Key`
`402`	Quota exhausted — balance empty
`403`	Forbidden — resource belongs to another organisation
`404`	Not found
`409`	Conflict — e.g. trigger path collision, missing agent owner
`422`	Validation error — check the `detail` array
`429`	Rate limited — check `Retry-After` header
`500`	Internal server error — retry with exponential backoff

Error Response Format

Response

json

{ "detail": "Human-readable description" }

Validation errors (422):

Response

json

{
  "detail": [
    {
      "loc": ["body", "phone_number"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Retry Strategy

typescript

async function withRetry<T>(fn: () => Promise<T>, maxAttempts = 3): Promise<T> {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err: any) {
      if (attempt === maxAttempts) throw err;
      // 4xx (except 429) are not retryable
      if (err.status < 500 && err.status !== 429) throw err;
      const delay = err.status === 429
        ? parseInt(err.headers?.get("Retry-After") ?? "5") * 1000
        : Math.pow(2, attempt) * 1000;
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error("Max retries exceeded");
}

Was this page helpful?

PreviousCampaign Status NextRate Limits