Errors
Resia uses standard HTTP status codes. A 2xx status means success. Any other status comes with a JSON body that explains the problem:
{
"error": {
"code": "rate_limited",
"message": "You have reached your concurrency limit of 10 calls at a time",
"request_id": "01K3..."
}
}
messageis written for people. Log it and show it to developers.codeis a short machine-readable value.request_ididentifies the request in your request logs. Include it when you contact support.
Base your retry logic on the HTTP status. Use code for finer handling when you need it.
Status codes
| Status | Meaning | Retry? |
|---|---|---|
200, 201 |
Success. | — |
202 |
Accepted. The work, such as a call, runs in the background. Read it by ID for the outcome. | — |
204 |
Success with no body. | — |
400, 422 |
The request is not valid. The message names the field and the rule, such as primary_participant: Value error, .... A map key or an unknown field name shows as *. A body with an unknown field also gets 422. |
No. Fix the request first. |
401 |
The bearer token is missing or not accepted. | No. See Authentication. |
402 |
Your prepaid balance is $0.00 or less. | After you add funds. See Billing. |
403 |
The token cannot do this action, such as an API key on a person-only endpoint, or an API key whose scope is too low. | No. |
404 |
Not found, or it belongs to another organization. | No. |
409 |
Conflict with the current state. For example: an idempotency key reused with a different body, an agent still in use, or a chat that already ended. | No. Read the current state first. |
429 |
A rate limit, or a short capacity shortage. | Yes, after Retry-After seconds. A refusal at the concurrent call limit has no Retry-After; try again after a call ends. See Rate limits. |
5xx |
A problem on Resia's side. | Yes, with backoff, and with the same idempotency key. |
Error codes
code takes one of these values:
| Code | Status | Meaning |
|---|---|---|
invalid_request |
422 |
A field is missing, has the wrong type or value, or is not defined. The message names a defined field. An undefined field name shows as *. |
unauthorized |
401 |
The bearer token is missing or not accepted. |
forbidden |
403 |
The token cannot do this action. |
not_found |
404 |
No such record in your organization. |
conflict |
409 |
The request conflicts with the current state, such as a reused idempotency key with a different body. |
slug_taken |
409 |
The organization slug is in use. |
invite_pending |
409 |
This person already has an open invitation. |
invite_expired |
410 |
The invitation link has expired. |
invite_revoked |
410 |
The invitation was cancelled. |
insufficient_funds |
402 |
Your prepaid balance is $0.00 or less. |
rate_limited |
429 |
You reached one of your rate limits. |
temporarily_unavailable |
429 |
Resia is short of capacity for a moment. Retry after a short wait. |
executor_error |
502 |
A service that Resia calls failed. Retry with backoff. |
unavailable |
503 |
Resia cannot serve the request now. Retry with backoff. |
Retry safely
Network errors and 5xx responses leave you unsure whether Resia did the work. Make retries safe:
- Send an
Idempotency-Keyheader onPOST /v1/calls,POST /v1/chats, batch submissions, top-ups, and 10DLC campaign registrations. Putidempotency_keyin the body forPOST /v1/orchestration-runs. - Use a new UUID for each new action, and the same key when you retry that action.
- A retry with the same key and body returns the original result. It does not repeat the call, the charge, or the text.
- Where the key is optional, a request without it still runs. A retry without a key can repeat the action, for example send the same text twice.
Failures after a 202
A single text send returns its recipient outcome under text_message. Read text_message.failure.code and text_message.failure.message for a recipient failure.
A 202 means that Resia accepted the work. The work itself can still fail later. Check the result:
- Calls: status
error, with the reason infailure. - Chats: status
failed. - Orchestration runs: status
failed, with the reason inerror_code. - Text messages: status
failedordelivery_unconfirmed.
Fullplex connections
Before a Fullplex connection opens, 401 rejects an invalid key, 402 rejects insufficient funds, and 403 rejects insufficient scope.
HTTP 429 rejects a concurrent-session limit breach. A temporary server fault returns 503.
The WebSocket error envelope has error.type, error.code, and error.message.

