Skip to content

Errors & Rate Limits

Errors are always returned as JSON with an HTTP status code outside 2xx. The shape is:

{
"detail": "Insufficient balance. You have 0.0 credits."
}

For validation errors (422), detail is an array of field-level issues:

{
"detail": [
{
"type": "missing",
"loc": ["body", "country_id"],
"msg": "Field required",
"input": null
}
]
}
Code Name Meaning
200 OK Request succeeded.
400 Bad Request Business-rule failure, e.g. invalid account_type, insufficient balance, or duplicate webhook URL.
401 Unauthorized Missing, malformed, or unknown X-API-Key.
403 Forbidden The account is banned, or you tried to access an order you don’t own.
404 Not Found Country/order not found, inactive, or out of stock.
422 Unprocessable Entity Request body failed validation.
429 Too Many Requests Rate limit exceeded.
500 Internal Server Error Something went wrong on our side. Retry after a short delay.

Requests are limited per API key using a fixed window.

Window Limit
Default 10 requests per 10 seconds

When you exceed the limit, the API responds with 429 and the standard error format. Back off for the rest of the window before retrying.

Robust error handling
import time
import requests
def fetch_otp(order_id):
url = f"https://su-persim.uz/api/v1/otp/{order_id}"
headers = {"X-API-Key": "supersim_YOUR_API_KEY"}
for attempt in range(5):
resp = requests.get(url, headers=headers)
if resp.status_code == 429:
time.sleep(resp.headers.get("Retry-After", 10))
continue
if resp.status_code == 200:
return resp.json()
resp.raise_for_status()
raise RuntimeError("rate limited")