# 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:

```json
{ "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 **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`.
