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.

errorHTTPMeaningWhat to doRetry?
unauthorized401The 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_scope403This 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_request400The 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_phone422The 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_network422The number is valid but not on Jawwal (059) or Ooredoo (056).Tell the customer only Jawwal and Ooredoo numbers can receive codes.No
idempotency_conflict409This 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_state409The 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_pending403The account is waiting for approval, so live keys can't send yet.Use a test key until OTP.ps approves the account.No
account_suspended403The account is suspended.Contact OTP.ps support.No
insufficient_balance402Not 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_limited429Too 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_reached429A 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_failed502The 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_found404No 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:

errorArabicEnglish
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 same Idempotency-Key so a request that actually went through isn't sent and charged twice.
  • Never retry automatically in a tight loop; respect retry_after.

View as Markdown