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": "This organization is limited to 30 calls per minute. Try again in about 41 seconds.",
    "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 or the rule. 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.	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. See Rate limits.
`5xx`	A problem on Resia's side.	Yes, with backoff, and with the same idempotency key.

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/workflow-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.

Failures after a 202

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.
Workflow runs: status failed, with the reason in error_code.
Text messages: status failed or delivery_unconfirmed.

Webhooks

Rate limits