Responses and errors

Success

{
  "success": true,
  "data": { "balance": 15230.5, "currency": "DZD" },
  "meta": { "timestamp": "2026-11-15T10:30:00.000Z" },
  "requestId": "req_8fK2mQx7Lp0aZ3nV1cWb"
}

Error

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance",
    "details": { "required": 500, "available": 120 }
  },
  "requestId": "req_Zk1o9P2nB7c4XqLw0eRt"
}

Branch on error.code, never on message. Messages can change; codes don't.
details is optional. For ERR_VALIDATION it lists the fields at fault: [{ "field": "MSSIDN", "message": "…" }].
requestId is also sent as the X-Request-ID header. Include it when you contact support.
The HTTP status always matches the code below.

Error codes

Code	HTTP	Meaning
`MISSING_ACCESS_TOKEN`	401	The X-Access-Token header is missing.
`INVALID_ACCESS_TOKEN`	401	The API key is unknown, revoked or malformed. details.attemptsLeft shows how many failures remain before the IP is blocked.
`IP_BLOCKED`	403	Too many failed authentication attempts from this IP. Wait 15 minutes.
`IP_NOT_ALLOWED`	403	The request IP is not in this key's allowed IP list.
`API_DISABLED`	403	API access is disabled for this key or account.
`ACCOUNT_DISABLED`	403	The account is suspended or not approved. Do not retry.
`READ_ONLY_KEY`	403	This key is READ-ONLY and cannot create top-ups.
`SERVICE_NOT_ALLOWED`	403	This service (mobile or internet top-up) is not enabled for your account.
`INSUFFICIENT_BALANCE`	403	Your balance is too low. details has required and available amounts. Nothing was charged.
`DUPLICATED_REF`	403	A top-up with this ref already exists. Check it with check-ref instead of sending again.
`ERR_STOCK`	403	This card value is out of stock. Try another value or retry later.
`ERR_VALIDATION`	400	The request is invalid. details lists the fields at fault. Nothing was charged.
`ERR_PHONE`	400	The phone or line number is invalid, does not exist, or does not match the type.
`NOT_FOUND`	404	The resource does not exist or belongs to another account.
`NOT_DEBT_PENDING`	409	resolve-debt was called for a top-up that is not DEBT_PENDING (already answered, expired or finished).
`DUPLICATE_IN_PROGRESS`	409	An identical top-up for this number is still being processed. Wait for it to finish.
`PAYLOAD_TOO_LARGE`	413	The request body is larger than 32 KB.
`RATE_LIMIT_EXCEEDED`	429	Too many requests. Wait for the number of seconds in Retry-After.
`INTERNAL_ERROR`	500	Unexpected error. For a send, check the top-up by ref before retrying.
`ERR_SERVICE`	503	The operator or provider is temporarily unavailable. Nothing was charged; retry later.
`AUTH_UNAVAILABLE`	503	Keys cannot be verified right now. Your key is fine; retry after Retry-After seconds.
`SERVICE_UNAVAILABLE`	503	The platform did not answer in time. The outcome of a send is unknown: check it by ref before retrying.

Which errors to retry

Retry	Codes
Yes, after a pause	`RATE_LIMIT_EXCEEDED`, `AUTH_UNAVAILABLE`, `ERR_SERVICE`, `DUPLICATE_IN_PROGRESS`
Only after checking the ref	`SERVICE_UNAVAILABLE`, `INTERNAL_ERROR` on a send
No, fix the request first	`ERR_VALIDATION`, `ERR_PHONE`, `INSUFFICIENT_BALANCE`, `ERR_STOCK`, `READ_ONLY_KEY`, `IP_NOT_ALLOWED`
No, read the existing top-up	`DUPLICATED_REF`
No, contact support	`ACCOUNT_DISABLED`, `API_DISABLED`

SuccessCopy Anchor Link

ErrorCopy Anchor Link

Error codesCopy Anchor Link

Which errors to retryCopy Anchor Link

On this page

Success

Error

Error codes

Which errors to retry