Copy page

Guides

Errors

The success envelope

Every successful response uses a data and metadata envelope.

Code
{
  "data": {
    "id": "trg_01HZX9Q2K8",
    "task_id": "task_01HZX9Q2K9",
    "status": "accepted",
    "created_at": "2026-09-15T09:30:00Z"
  },
  "metadata": {
    "request_id": "my-request-1"
  }
}

A list response adds pagination to the metadata.

Code
{
  "data": [],
  "metadata": {
    "request_id": "my-request-1",
    "pagination": {
      "total": 150,
      "limit": 20,
      "offset": 0,
      "has_more": true
    }
  }
}

metadata.request_id is the echo of the X-Request-ID header. Ringtime includes it only when you send that header. Send one on each request. It makes support much faster.

The error shape

An error does not use the envelope. There are two error shapes. Which one you get depends on where the request failed.

Schema errors: HTTP 422 with detail

A body that does not match the schema is rejected before Ringtime reads it. A missing required field, a wrong type, a bad enum value and a value that breaks its own field's rule all land here. A phone number without a country calling code is the common one. The answer is HTTP 422 and a list under detail, one entry per broken field.

Code
{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "campaign"],
      "msg": "Field required"
    }
  ]
}

Field	Type	What it is
loc	array	Path to the broken field, starting with body.
msg	string	Text for a human. Do not parse it.
type	string	The rule that failed, for example missing.

There is no error_code on this shape. Read loc to find the field to fix. An entry can carry more keys, such as input, the value you sent. Read the three above and ignore the rest.

One exception: a body that matches the schema but asks for something the campaign cannot do is also answered with HTTP 422, but with the error_code shape below. Today that is LANGUAGE_NOT_SUPPORTED (with details.supported listing the languages on offer) and CHANNEL_MISMATCH. Tell the two apart by the presence of detail (a list) versus error_code (a string).

Every other error: error_code

Once the body parses, Ringtime answers a refusal with this shape.

Code
{
  "error_code": "VALIDATION_ERROR",
  "message": "missing required id types: ['application']",
  "details": null,
  "request_id": "my-request-1"
}

Field	Type	What it is
error_code	string	Machine-readable code in UPPER_SNAKE_CASE.
message	string	Text for a human. Do not parse it.
details	object or null	More context. The keys depend on the error.
request_id	string or null	Echo of X-Request-ID, when you sent one.

Branch on error_code, never on message. The message text can change at any time.

Test both shapes. A client that reads error_code on every failure will read undefined on a 422.

Status codes

Status	Meaning
400	The body parses, but Ringtime cannot use it.
401	The API key is missing or invalid.
403	The key is valid but not allowed to do this.
404	The resource does not exist.
409	Conflict. For example a duplicate.
422	The body does not match the schema (detail shape), or names a language or channel the campaign cannot serve (error_code shape).
429	Too many requests. The rate limit is per client address and per route.
500	Unexpected server error.
502	A system Ringtime had to read returned an error.

Error codes

Code	Status	When
BAD_REQUEST	400	The request is not usable.
VALIDATION_ERROR	400	The body parsed, but a value cannot be used.
INVALID_SOURCE	400	The source you named is not allowed for your organization.
FORBIDDEN	403	The key may not do this.
NOT_FOUND	404	The resource does not exist.
CONFLICT	409	The request clashes with something that already exists.
INTERNAL_ERROR	500	Unexpected server error.

Some operations add a more exact code when a client must tell two errors of the same status apart. The API reference lists the codes for each operation.

How to retry

Retry these:

• 429. Wait, then send the same request again.
• 409 with error_code SOURCE_RECORD_NOT_AVAILABLE. The record is not readable yet. The Retry-After header gives the wait in seconds. Send the same body again after that wait.
• 409 with error_code CAMPAIGN_NOT_READY. Your request is correct, but the campaign is still being set up on Ringtime's side (it has no agent yet). Keep the body and send it again later — for example on your next scheduled run. Do not retry immediately: nothing you change will make it pass until Ringtime finishes the campaign.
• 5xx, including 502 with error_code SOURCE_API_ERROR. Use an increasing wait time.

Do not retry any other 4xx. Nothing changes until you correct the request. That includes 409 with DUPLICATE_TASK: the task already exists, and details.existing_task_id names it.

Keep the request_id of a failed request. Give it to Ringtime support.