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..."
  }
}
  • message is written for people. Log it and show it to developers.
  • code is a short machine-readable value.
  • request_id identifies 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-Key header on POST /v1/calls, POST /v1/chats, batch submissions, top-ups, and 10DLC campaign registrations. Put idempotency_key in the body for POST /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 in failure.
  • Chats: status failed.
  • Orchestration runs: status failed, with the reason in error_code.
  • Text messages: status failed or delivery_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.