Errors

Status codes

Code	Meaning	May charge
200	Success. The charge may be 0.	✅ Yes
400	Bad request. Also returned when balance is insufficient.	❌ No
401	Missing or invalid Api-Key.	❌ No
404	Resource not found.	❌ No
422	Request validation failed.	❌ No
429	A request-per-minute or concurrency limit was exceeded.	❌ No
500	Internal service error.	❌ No
503	The service is temporarily unavailable.	❌ No

Error shape

Documented API errors other than validation errors return a detail string:

{ "detail": "Error description" }

Validation errors (422) use the FastAPI structured format:

{
  "detail": [
    {
      "loc": ["query", "name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

• loc — path to the bad field.
• msg — human-readable message.
• type — programmatic error type.

Examples

401 — invalid or missing token

{ "detail": "Not authenticated" }

400 — insufficient balance

{ "detail": "Not enough balance to perform this action. Please top up your balance." }

For insufficient balance on a paid endpoint, the response also includes Telesint-Billing-Charged: 0, Telesint-Billing-Balance, and Cache-Control: private, no-store. Other 400, 404, 422, 500, and 503 responses do not guarantee billing headers.

404 — resource not found

{ "detail": "User not found" }

429 — rate limit exceeded

{ "detail": "Rate limit exceeded", "reason": "rpm" }

The response includes Retry-After. The reason is either rpm or concurrency; see Rate limits.

503 — rate limiter unavailable

{ "detail": "Rate limiter is temporarily unavailable" }

This response includes Retry-After: 5 and is not charged.

Retry strategy

Status	Retry?
2xx	—
400, 401, 404, 422	No. Fix the request / credentials / balance, then retry.
429	Yes. Wait for the number of seconds in Retry-After.
5xx	Yes. Honor Retry-After when present; otherwise use exponential backoff: 1s, 2s, 4s, 8s.