TitanSim / Developers
Errors
Stable error codes and retry guidance.
Error envelope
Every error is JSON: { "error": { "code", "message", "request_id", "details"? } }. Use code for branching and request_id when contacting support.
Example shape
{"error":{"code":"validation_error","message":"Invalid request","request_id":"...","details":{"field":"plan_id"}}}Retry behavior
For a timed-out order or top-up, retry with the same reference and payload. For 429, honor Retry-After. A provider_error means nothing was charged.
| HTTP | Code | When |
|---|---|---|
| 400 | validation_error | Body or query validation failed; details.field may identify the field. |
| 401 | unauthorized | The key is missing, invalid, revoked, or expired. |
| 402 | insufficient_balance | Prepaid balance is below the order or top-up amount. |
| 403 | forbidden | The partner or company is inactive, or the mode is not permitted. |
| 404 | not_found | The requested resource does not exist or is not yours. |
| 409 | reference_in_progress | A request with this reference is currently processing. |
| 422 | reference_mismatch | The reference was used with a different payload. |
| 422 | unprocessable | The request cannot be fulfilled in this resource state. |
| 429 | rate_limited | The per-key rate limit was exceeded. |
| 500 | internal_error | TitanSim encountered an internal error. |
| 502 | provider_error | The carrier side failed; nothing was charged. |
| 503 | unavailable | The API is temporarily unavailable. |