Errors and request IDs
The error body, the requestId to quote to support, the codes you can get and which errors to retry.
Error format
Every error has an HTTP status and a JSON body with a stable code (to branch on in your code), a human message (not stable, do not parse it) and a requestId.
{
"error": {
"code": "agent_not_found",
"message": "Agent not found",
"requestId": "req_01J9Z3K8M2V5N7Q1R4T6W8Y0AB"
}
}The same identifier is returned in the X-Request-Id header of every response, successful or not. Log it with each call: it is how the request is found in the API logs of the dashboard and how support investigates.
const res = await fetch("https://infynia.quantylcore.com/api/v1/calls/CALL_ID", {
headers: { Authorization: `Bearer ${process.env.INFYNIA_API_KEY}` },
});
if (!res.ok) {
const { error } = await res.json();
// Log requestId: support finds the request with it.
console.error(error.code, error.message, error.requestId);
throw new Error(error.code);
}Codes
| Status | Codes | Meaning |
|---|---|---|
| 400 | invalid_body, invalid_number, invalid_query, invalid_idempotency_key | The request is malformed. Fix it, do not retry as is. |
| 401 | unauthorized | Missing, invalid, expired or revoked key. |
| 403 | forbidden, forbidden_agent, plan_required, test_mode_not_supported, country_not_allowed, do_not_call | The key is not allowed to do this, or the call is blocked by a guard (countries, do-not-call list). |
| 404 | not_found, agent_not_found | The resource does not exist for this organization. |
| 409 | agent_inactive, not_cancellable, idempotency_in_progress | The resource is not in a state that allows the action. |
| 422 | outside_hours, idempotency_mismatch | The request is valid but refused: outside the call window, or an idempotency key reused with another body. |
| 429 | rate_limited, concurrent_limit, hourly_limit, pending_limit | Too many requests or too many calls. Wait, then retry. |
| 500, 502 | internal_error, call_failed | Server-side failure. Retry with backoff. |
The reference lists the codes each endpoint can return. New codes can be added over time: handle unknown codes by their HTTP status.
What to retry
4xxerrors other than429: no, the same request will fail again.429: yes, after the delay of theRetry-Afterheader.5xxand network errors: yes, with exponential backoff, and with the sameIdempotency-Keyon aPOST.