Reference
Errors
Every error code the API can answer, what it means and what your integration should do.
Every error has an HTTP status of 400 or more and this body:
{ "error": "invalid_phone", "message": "The phone number is not a valid Palestinian mobile number." }Switch on error, never on message (the wording may change). rate_limited also has retry_after (seconds) and a Retry-After header.
error | HTTP | Meaning | What to do | Retry? |
|---|---|---|---|---|
unauthorized | 401 | The API key is missing, malformed, unknown or revoked. | Send Authorization: Bearer <key> with a key from the dashboard. Check the server's environment variable, not the code. | No |
insufficient_scope | 403 | This API key isn't allowed to do this (its permissions don't include send, check or read). | Use a key with the needed permission, or create one on the dashboard (API keys). | No |
invalid_request | 400 | The body isn't a JSON object, or a field is missing or has a value that isn't allowed. | Fix the request: phone is required on send; locale is ar or en; purpose is one of the listed purposes; check needs code and id or phone. | No |
invalid_phone | 422 | The number is not a valid Palestinian mobile number. | Ask the customer to correct the number. Accepted: 059XXXXXXX / 056XXXXXXX, with or without +970 / +972 / 00970. | No |
unsupported_network | 422 | The number is valid but not on Jawwal (059) or Ooredoo (056). | Tell the customer only Jawwal and Ooredoo numbers can receive codes. | No |
idempotency_conflict | 409 | This Idempotency-Key was already used with a different request. | Use a new key for every new send; reuse a key only to retry the exact same request. | No |
invalid_state | 409 | The verification link can't be changed any more: it is already approved, expired or canceled. | Read the link's status; create a new link if the customer still needs to confirm. | No |
account_pending | 403 | The account is waiting for approval, so live keys can't send yet. | Use a test key until OTP.ps approves the account. | No |
account_suspended | 403 | The account is suspended. | Contact OTP.ps support. | No |
insufficient_balance | 402 | Not enough credit left for this message. | Top up the balance. Show the customer a friendly 'try again later' message and alert your team. | No |
rate_limited | 429 | Too many codes for this number (or this account) in a short time. | Wait retry_after seconds (also in the Retry-After header). Show the customer a countdown before they can resend. | Yes, later |
spending_limit_reached | 429 | A spending limit is reached: the account's daily or monthly message limit, the daily ceiling set by OTP.ps, or this key's daily limit. | No more live codes until it resets (retry_after, in seconds). Alert your team; raise the limit on the dashboard (Settings) if it's expected. | Yes, later |
sms_failed | 502 | The text message gateway refused or couldn't take the message. Nothing was charged. | Let the customer try again in a moment. If it keeps happening, contact OTP.ps support. | Yes, later |
not_found | 404 | No verification with that id (or for that number) exists for this key's account and mode. | Check the id from the send answer, and that you check with a key of the same mode (test or live) that sent it. | No |
A wrong code is not an error: /verify/check answers 200 with valid: false and attempts_left.
Showing errors to customers
Map codes to your own messages, in the customer's language; never show the raw message. For example:
error | Arabic | English |
|---|---|---|
invalid_phone | رقم الجوال غير صحيح. | Please check the mobile number. |
unsupported_network | نرسل الرموز لأرقام جوال و Ooredoo فقط. | We can only send codes to Jawwal and Ooredoo numbers. |
rate_limited | انتظر قليلاً قبل طلب رمز جديد. | Please wait before asking for a new code. |
sms_failed | تعذّر إرسال الرسالة. حاول مرة أخرى. | We couldn't send the message. Please try again. |
| anything else | تعذّر التحقق الآن. حاول لاحقاً. | Verification isn't available right now. |
unauthorized, insufficient_scope, account_pending, account_suspended, insufficient_balance and spending_limit_reached are problems for your team, not the customer: log them and alert someone.
Retrying
- Retry only errors marked "Yes, later" above, and network failures.
- For
/verify/send, retry with the sameIdempotency-Keyso a request that actually went through isn't sent and charged twice. - Never retry automatically in a tight loop; respect
retry_after.