Developers
Errors & limits
JSON errors always include a human message and a stable code. Branch on code in software; show error to people.
Error shape
Body is { "error": "...", "code": "..." }. HTTP status matches the table below.
Codes
| code | HTTP | When |
|---|---|---|
MISSING_API_KEY | 401 | No X-API-Key / Bearer token |
INVALID_API_KEY | 401 | Key format or secret is wrong |
ACCOUNT_SUSPENDED | 403 | Account disabled |
INSUFFICIENT_BALANCE | 402 | Wallet cannot cover the charge |
SERVICE_UNAVAILABLE | 404 / 502 | No stock, or the service is temporarily down |
RENTAL_NOT_FOUND | 404 | Unknown id, or it belongs to another account |
CANCEL_NOT_ALLOWED | 404 | Only WAITING temporary rentals can be cancelled |
INVALID_COUNTRY | 400 | Country not in GET /api/v1/countries |
VALIDATION_ERROR | 400 | Missing or invalid JSON fields |
RATE_LIMITED | 429 | Too many requests — honor Retry-After |
Idempotency
For POST /api/v1/rentals, POST .../renew, and long-term create, send Idempotency-Key: <uuid> (max 256 chars). Reusing the same key with the same body within 24 hours returns the original response instead of charging twice.
IDEMPOTENCY_IN_PROGRESS— 409, same key still processingIDEMPOTENCY_KEY_REUSED— 422, same key but different bodyIDEMPOTENCY_KEY_REQUIRED— 400, bulk long-term rent (quantity > 1) without a key
Rent without a key is not safe to retry
Two clicks without
Idempotency-Key can create two numbers and two charges. Always send a unique key per intended rent.Rate limits
Per API key (default 100 requests/minute). Public endpoints are limited per IP. HTTP 429 includes a Retry-After header and code: "RATE_LIMITED".