psykeBlogOpen PSYKE

Rate limits & billing

The limits, wallet model, and per-number pricing that govern every order.

Rate limit

All endpoints share one throttle scope: 120 requests / minute, applied per API key (not per IP, so resellers behind a shared NAT do not eat each other's quota). Exceeding it returns 429 with code throttled; the message states how many seconds to wait before retrying.

429 response
HTTP/1.1 429 Too Many Requests

{ "message": "Request was throttled. Expected available in 30 seconds.", "code": "throttled", "is_error": true }

Prepaid wallet

  • Currency: 1 token = 1 USD. Balances and costs are USD, to 6 decimal places.
  • Prepaid: you must have funds before submitting. Top-ups are arranged with your account manager (no self-serve top-up endpoint yet).
  • Charged at submit time (POST /orders). The charge is input_count × price_per_number, where input_count is the count of valid, deduplicated numbers accepted from your file. The exact cost and wallet_balance_after are returned in the submit response.
  • Atomic: a failed submit never leaves a partial charge.
  • Auto-refund on failure: if an order ends in failed, the exact amount you were charged is automatically refunded.

Check your balance

cURL
curl -s "https://api.p-syke.com/api/reseller/balance" -H "X-Reseller-API-Key: $KEY"
Response
{ "token_balance": "98.460000", "currency": "USD" }

token_balance is a precise decimal string — parse it as a decimal, not a float, if you need exact accounting.

Per-number pricing

Each service has its own USD-per-number rate — see the services catalog for the full table, or fetch it live with GET /services. Example: 2,000 numbers × tg-active (0.0004) = $0.80.

File limits & rules

  • Format: plain text, one phone number per line, read as UTF-8.
  • Digits only, no + prefix. The country field supplies the dialing context. Numbers are normalized to a canonical digit form for that country (e.g. US 10-digit → 1XXXXXXXXXX), malformed/empty lines are dropped, and duplicates removed.
  • Minimum order: 2,000 valid numbers after normalization (fewer → MIN_NUMBERS, nothing charged).
  • Max file size: 20 MB (larger → FILE_TOO_LARGE).

Idempotency

Send an Idempotency-Key header (any unique string, ≤ 64 chars — a UUID works well) with every submit. If your request times out and you retry with the same key, the API returns the original order (HTTP 200 with "replayed": true) instead of creating and charging a second one. Keys are scoped to your account. Without the header, every retry that reaches the server creates a new, separately charged order.