Agent APIReference
Errors and status codes
The error envelope, HTTP status codes, and CLI exit codes.
Every error response is a JSON object with a stable shape. This page lists the envelope, the HTTP status codes the gateway returns, and the CLI exit codes.
Error envelope
Every non-2xx response body has the same shape: an error object with a machine-readable code and a human-readable message.
{"error":{"code":"not_found","message":"human readable detail"}}HTTP status codes
| Status | Code | When |
|---|---|---|
| 400 | bad_request | Malformed input, e.g. an unknown webhook event or a webhook URL whose host is loopback or a private address |
| 401 | unauthorized | Missing or invalid token |
| 403 | forbidden | Not owner or not allowed |
| 403 | insufficient_scope | Token lacks the required scope |
| 403 | not_prearmed | Remote recording start without pre-arm |
| 403 | license_required | A Pro-gated action without the license |
| 404 | not_found | Unknown id |
| 409 | conflict | State conflict, e.g. already recording, or a diarization rerun conflict, or webhooks disabled |
| 413 | payload_too_large | Request body exceeds the size limit, e.g. an import upload |
| 422 | invalid_request | Unprocessable, e.g. empty transcript on regenerate, bad config body |
| 429 | too_many_requests | Pairing request cap |
| 500 | internal | Server error |
| 503 | service_unavailable | A component is warming up, or Integrations was disabled at runtime (the listener stays bound but every route returns 503 until re-enabled and the app restarts). The runtime-disable case has no JSON body. |
A malformed JSON body (not valid JSON at all) returns 400 bad_request; a well-formed body that fails validation returns 422 invalid_request.
CLI exit codes
| Exit code | Meaning |
|---|---|
| 0 | ok |
| 1 | generic error, including a server validation error |
| 2 | timeout |
| 3 | cannot connect (the app is not running) |
| 4 | denied (401 or 403) |
Do not retry-loop on exit 3
Exit code 3 means the app is not running or Integrations is off. Surface that to the user; do not retry in a tight loop.
Last updated on