Error codes

The CheckYout API uses standard HTTP status codes and returns structured JSON error responses.

Error format

Most error responses follow this shape:

{
  "error": "Short error description",
  "details": "Optional extra information"
}

Field	Type	Description
`error`	`string`	Short, machine-readable error description. Always present.
`details`	`string`	Optional extra information about the cause.

Validation errors

When the request body has missing or invalid fields, we extend the error response with an issues array of field-level details so you know exactly which entry to fix:

{
  "error": "Validation error",
  "issues": [
    { "path": "phone", "message": "Phone must be in E.164 format (starting with +)", "code": "invalid_string" },
    { "path": "device_id", "message": "Required", "code": "invalid_type" }
  ]
}

Field	Type	Description
`issues[].path`	`string`	Dot-separated path to the field in the body (e.g. "phone" or "settings.timezone").
`issues[].message`	`string`	Human-readable description of the problem (in English).
`issues[].code`	`string`	Machine-readable error code (e.g. "invalid_type", "invalid_string", "too_small").

Which format applies when?

Endpoints with body validation (POST/PATCH/DELETE on /api/v1/*) return the extended format with an issues array on validation failures. Auth, rate-limit, and server errors keep the simpler error format.

HTTP status codes

Code	Meaning	Typical cause	Example
`200`	OK	Request processed successfully	`{"success":true,"message_sid":"SM..."}`
`400`	Bad Request	Validation failed (see issues array)	`{"error":"Validation error","issues":[…]}`
`400`	Bad Request	Body is not valid JSON	`{"error":"Invalid JSON body"}`
`401`	Unauthorized	Missing or invalid API key	`{"error":"Invalid or missing API key"}`
`404`	Not Found	Device does not exist or does not belong to your account	`{"error":"Device not found or does not belong to your account"}`
`429`	Too Many Requests	Rate limit exceeded (e.g. /api/v1/notify: 30/min/IP)	`{"error":"Too many requests"}`
`500`	Internal Server Error	WhatsApp delivery failed	`{"error":"Failed to send WhatsApp","details":"..."}`

Error handling

4xx errors: Check your request — API key, required fields, phone-number format, device assignment.
5xx errors: Server-side issue. Retry the request after a short wait.
Always evaluate the HTTP status code and the error field.

Retry strategy

For 5xx errors we recommend a retry with exponential backoff (e.g. 1s, 5s, 30s) and at most 3 attempts.

Next: Changelog