Errors & Rate Limits
Error format
Section titled “Error format”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 } ]}Status codes
Section titled “Status codes”| 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. |
Rate limits
Section titled “Rate limits”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.
Handling errors in code
Section titled “Handling errors in code”import timeimport 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")<?php
function fetchOtp($orderId) { $url = "https://su-persim.uz/api/v1/otp/{$orderId}"; for ($attempt = 0; $attempt < 5; $attempt++) { $ch = curl_init($url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, [ "X-API-Key: supersim_YOUR_API_KEY", ]); $resp = curl_exec($ch); $code = curl_getinfo($ch, CURLINFO_RESPONSE_CODE); curl_close($ch);
if ($code === 429) { sleep(10); continue; } if ($code === 200) { return json_decode($resp, true); } throw new RuntimeException("HTTP $code"); } throw new RuntimeException("rate limited");}async function fetchOtp(orderId) {const url = `https://su-persim.uz/api/v1/otp/${orderId}`;const headers = { "X-API-Key": "supersim_YOUR_API_KEY" };for (let attempt = 0; attempt < 5; attempt++) { const res = await fetch(url, { headers }); if (res.status === 429) { await new Promise((r) => setTimeout(r, 10000)); continue; } if (res.ok) return res.json(); throw new Error(`HTTP ${res.status}`);}throw new Error("rate limited");}