Errors
Every error is a problem document with a stable code. Find a code, its usual cause and how to recover.
Sandbox: test money only. No request moves real money.
When a request cannot be served, the response is an RFC 9457 problem with the media type application/problem+json. Branch on code, show detail to a person, and keep request_id for support. Any status other than the ones an operation lists for success is an error of this shape.
The problem document
| Field | Meaning |
|---|---|
| Typetype | The address of this code's entry on this page: the documentation's /errors#<code>. The examples on these pages show about:blank instead, so they name no host but the sandbox's. |
| Titletitle | A short human summary of the status. |
| Statusstatus | The HTTP status code, repeated in the body. |
| Codecode | The stable machine code. Every code is listed below. |
| Categorycategory | What kind of problem it is, fixed per code: authentication, authorisation, validation, balance, rate_limit, provider, webhook, internal, timeout, unknown_outcome. internal_error on a request that changes your balance is unknown_outcome: it may have been accepted, so retry with the same Idempotency-Key. |
| Detaildetail | What went wrong, in a sentence for a person. Its wording may change. |
| Paramparam | The request field at fault, when there is one. |
| Request IDrequest_ | The id of this request on our side. |
Two headers accompany an error: Request-Id and Retry-After. Retry-After is set on 429 and on some 503 responses, in seconds.
{ "type": "about:blank", "title": "Too many requests", "status": 429, "code": "rate_ limited", "category": "rate_ limit", "detail": "Too many requests. Retry after the time in Retry-After. ", "param": null, "request_ id": "req_ 01K7SAMP000000000000000090"}Rules for every error
- Branch on
code, never ondetailortitle. Those two are for people and may change. - A timeout is not an error code. The outcome is unknown: send the same request with the same key, or fetch the order by your
reference. - An unknown code is a generic failure. New codes may be added; fall back to the
statusandcategorythe problem carries. - Log
request_idwith every failure. It identifies the request on our side.
Every example on these pages handles a failure the same way, in each language: it reads the problem from the response and raises it with its status, code, title and request_id. The Error tab is the problem it would raise.
// npm install axiosimport axios from 'axios';// One key per purchase: make it once, keep it with the purchase, and send the same key on every retry.const idempotencyKey = process. env. IDEMPOTENCY_ KEY;if ( !idempotencyKey) throw new Error( 'Set IDEMPOTENCY_ KEY once for this purchase ( a new UUID) and keep it for every retry');try { const { status, data: order } = await axios. post( 'https:// sandbox-api. nasfampay. com/ v1/ orders', { quote_ id: 'quo_ 01K7SAMP000000000000000090', reference: 'TEST-0001', }, { headers: { Authorization: `Bearer ${process. env. NASFAM_ SANDBOX_ KEY}`, 'Idempotency-Key': idempotencyKey, }, }, ); console. log( status, order);} catch ( error) { if ( !axios. isAxiosError( error) || !error. response) throw error; const problem = error. response. data; throw new Error( `${problem. status} ${problem. code}: ${problem. title} ( request ${problem. request_ id})`);}The codes
The API answers with 39 codes. Each has one HTTP status and one category, as the contract's table states them, and its own anchor: the problem's type links straight to it.
| Code | Status | Category | Send the same request again? |
|---|---|---|---|
invalid_request | 400 | validation | No |
unknown_field | 400 | validation | No |
insufficient_scope | 403 | authorisation | No |
key_environment_mismatch | 401 | authentication | No |
insufficient_funds | 402 | balance | Not until the balance covers it |
quote_expired | 409 | validation | No |
quote_already_used | 409 | validation | No |
price_changed | 409 | validation | No |
duplicate_reference | 409 | validation | No |
idempotency_key_reused | 422 | validation | No |
idempotency_in_progress | 409 | unknown_outcome | Yes, after a short wait |
queue_limit | 429 | rate_limit | Yes, later |
rate_limited | 429 | rate_limit | Yes, after Retry-After |
account_restricted | 403 | authorisation | No |
capacity_exhausted | 503 | provider | Yes, later |
pricing_unavailable | 503 | provider | Yes, later |
product_unavailable | 422 | authorisation | Not until the product is available |
recipient_not_found | 422 | validation | No |
recipient_not_eligible | 422 | validation | No |
not_found | 404 | validation | No |
invalid_api_key | 401 | authentication | No |
key_expired | 401 | authentication | No |
idempotency_key_required | 400 | validation | Yes, with a key |
payload_too_large | 413 | validation | No |
unsupported_media_type | 415 | validation | No |
browser_request_refused | 403 | authentication | No |
webhook_url_refused | 422 | webhook | No |
endpoint_limit | 409 | webhook | No |
service_unavailable | 503 | internal | Yes, after Retry-After |
internal_error | 500 | internal | Yes, with the same key |
order_limit_exceeded | 422 | validation | No |
provider_unavailable | 503 | provider | Yes, after Retry-After |
lookup_expired | 409 | validation | No |
recipient_mismatch | 409 | validation | No |
recipient_lookup_required | 422 | validation | Yes, citing a lookup |
product_not_permitted | 403 | authorisation | No |
spending_limit_reached | 422 | validation | Not until the limit resets or is raised |
statement_not_ready | 409 | validation | Not until it is ready |
ip_not_allowed | 403 | authorisation | No |
invalid_request
The request is malformed, or a value is outside what the operation allows. param names the field.
- HTTP status. 400.
- Usual cause. A
quantityoutside the bounds onGET /products, amonthsother than 3, 6 or 12, a missing required field, or anIdempotency-Keythat is not 16 to 64 characters. - How to recover. Fix the value and send the corrected request.
- Safe to retry? No. The same request fails the same way.
- Related. API reference
unknown_field
The body carries a field the operation does not take. param names it.
- HTTP status. 400.
- Usual cause. A misspelt field, a field from another operation, or
quantityandmonthssent for the wrong product. Requests are strict. - How to recover. Remove the field.
- Safe to retry? No. The same body is refused again.
- Related. API reference
insufficient_scope
The key is not allowed this operation.
- HTTP status. 403.
- Usual cause. The key was issued with fewer permissions than the request needs. The contract does not list the scopes a key can hold.
- How to recover. Use a key that has the scope. You choose what a key may do when you create it in your dashboard.
- Safe to retry? No. The key does not change between attempts.
- Related. Authentication and keys
key_environment_mismatch
The key and the host belong to different environments.
- HTTP status. 401.
- Usual cause. A
nbk_test_key sent to the live host, or anbk_live_key sent to the sandbox. - How to recover. Send each key to its own host. Keep the two in separate configuration.
- Safe to retry? No. Change the key or the host first.
- Related. Authentication and keys
insufficient_funds
The available balance is insufficient to cover the order.
- HTTP status. 402.
- Usual cause. The order costs more than
available. Money that isheldby other orders, or still inpending_funding, does not count. - How to recover. Read
GET /balance, fund the balance, then order again. - Safe to retry? Not until the balance covers it. The same request is refused while
availableis short. - Related. Funding your account
quote_expired
The quote is past its expires_at. A quote locks a price for up to 60 seconds.
- HTTP status. 409.
- Usual cause. Too long passed between the quote and the order, often because a person was asked to confirm in between.
- How to recover. Create a new quote and order from it.
- Safe to retry? No. An expired quote stays expired.
- Related. Orders and statuses
quote_already_used
The quote was already turned into an order. A quote is used once.
- HTTP status. 409.
- Usual cause. A second order request for the same quote with a new
Idempotency-Key, usually a retry that made a fresh key. - How to recover. Find the first order by your
reference, or list recent orders and matchquote_id. Do not quote again until you know that order's state. - Safe to retry? No. The order you wanted already exists.
- Related. Orders and statuses
price_changed
The current price does not fit the max_amount you sent on a direct order.
- HTTP status. 409.
- Usual cause. The price moved since you last read it, or the ceiling was set too low.
- How to recover. Create a quote to see the current price, then decide whether to order.
- Safe to retry? No. Not with the same
max_amount. - Related. Orders and statuses
duplicate_reference
Another order already carries this reference.
- HTTP status. 409.
- Usual cause. The same invoice or cart line was sent as a new order with a new
Idempotency-Key. - How to recover. Fetch the existing order with
GET /orders?reference=and use it. Do not order again. - Safe to retry? No. The reference stays taken.
- Related. Orders and statuses
idempotency_key_reused
This Idempotency-Key was already used for a different request.
- HTTP status. 422.
- Usual cause. One key shared by two orders, or a body that changed between the first attempt and a retry.
- How to recover. Make one key per operation and store it with the thing you are creating. A retry must send the body unchanged.
- Safe to retry? No. Send the original body with this key, or a new key with the new body.
- Related. Idempotency and safe retries
idempotency_in_progress
The first request with this key is still being processed.
- HTTP status. 409.
- Usual cause. A retry sent before the first attempt finished, or two workers sending the same request at once.
- How to recover. Wait a moment, then send the same request with the same key.
- Safe to retry? Yes, after a short wait. The same request with the same key returns the operation.
- Related. Idempotency and safe retries
queue_limit
The account already has max_queued orders in progress.
- HTTP status. 429.
- Usual cause. A batch that creates orders faster than they finish.
- How to recover. Wait for orders to reach a final state, then send the request again. Read
max_queuedonGET /account. - Safe to retry? Yes, later. With the same key and body, once orders have finished.
- Related. Orders and statuses
rate_limited
Too many requests.
- HTTP status. 429.
- Usual cause. A polling loop, or many workers sharing one key.
- How to recover. Wait at least the seconds in
Retry-After, then send the request again. - Safe to retry? Yes, after
Retry-After. With the same key if the request changes your balance. - Related. Rate limits
account_restricted
The account may not do this.
- HTTP status. 403.
- Usual cause. The state of the organisation.
kyb_statusonGET /accountshows it. - How to recover. Read
kyb_status. Nothing in the request can change the answer. - Safe to retry? No. The account has to change first.
- Related. Complete Live activation
capacity_exhausted
Delivery capacity is used up for now.
- HTTP status. 503.
- Usual cause. Nothing in your request. The limit is on our side.
- How to recover. Send the request again later. If the response carries
Retry-After, wait at least that long. - Safe to retry? Yes, later. With the same key if the request changes your balance.
- Related. Rate limits
pricing_unavailable
No price can be computed right now.
- HTTP status. 503.
- Usual cause. Nothing in your request.
- How to recover. Send the request again later.
- Safe to retry? Yes, later. With the same key if the request changes your balance.
- Related. Create a quote
product_unavailable
The product is not orderable right now.
- HTTP status. 422.
- Usual cause. The product has
availablefalse, or astatusofplanned, onGET /products. - How to recover. Read
GET /productsand order only what isavailable. - Safe to retry? Not until the product is available. Check
GET /productsfirst. - Related. List products
recipient_not_found
No Telegram account has this username.
- HTTP status. 422.
- Usual cause. A typing mistake, or a username that changed.
- How to recover. Check the username with your customer and quote again.
- Safe to retry? No. The same username is refused again.
- Related. Create a quote
recipient_not_eligible
The recipient cannot receive this product.
- HTTP status. 422.
- Usual cause. A fact about the recipient's Telegram account, not about your request.
- How to recover. Tell your customer. Another product or another recipient may still work.
- Safe to retry? No. The answer does not change by asking again.
- Related. Create a quote
not_found
No object has this id, or there is no such route.
- HTTP status. 404.
- Usual cause. An id from the other environment, a truncated id, or a path that is not in the contract.
POST /does not exist on the live host.sandbox/ funding/ deposits - How to recover. Check the id and the path.
- Safe to retry? No. The same address answers the same way.
- Related. API reference
invalid_api_key
The key was not accepted.
- HTTP status. 401.
- Usual cause. A key that is missing, mistyped, cut short or revoked. Every key is checked in the database on every request, so a revoked key is refused from the next request on.
- How to recover. Send
Bearerfollowed by the whole key, and check in your dashboard that the key is still active. - Safe to retry? No. The same key is refused again.
- Related. Authentication and keys
key_expired
The key is past its expiry.
- HTTP status. 401.
- Usual cause. A key with its correct secret, used after it expired.
- How to recover. Create a new key in your dashboard and send the request with it.
- Safe to retry? No. Not with the expired key.
- Related. Authentication and keys
idempotency_key_required
The operation needs an Idempotency-Key and the request had none.
- HTTP status. 400.
- Usual cause.
POST /ordersorPOST /sent without the header.sandbox/ funding/ deposits - How to recover. Make a key, store it with what you are creating, and send the request with it.
- Safe to retry? Yes, with a key. Send the same request with an
Idempotency-Key, and reuse that key on every retry. - Related. Idempotency and safe retries
payload_too_large
The request body is over 16 KB. It is refused before the key is checked, and nothing more is read.
- HTTP status. 413.
- Usual cause. Large
metadata, or the wrong data sent as the body. - How to recover. Send a smaller body.
- Safe to retry? No. The same body is refused again.
- Related. API reference
unsupported_media_type
The body is not sent as JSON.
- HTTP status. 415.
- Usual cause. A body without the
application/jsonmedia type. - How to recover. Send the body as
application/json. - Safe to retry? No. Not until the body is JSON.
- Related. API reference
browser_request_refused
The request came from a browser, and the API does not take those.
- HTTP status. 403.
- Usual cause. A call from code that runs in a web page, where anyone who opens the page can read the key.
- How to recover. Call the API from your server, and keep the key there.
- Safe to retry? No. A browser is refused every time.
- Related. Authentication and keys
webhook_url_refused
The API will not deliver to this endpoint URL.
- HTTP status. 422.
- Usual cause. An address that is not a public
https://one. - How to recover. Register a public
https://address. - Safe to retry? No. The same URL is refused again.
- Related. Webhooks
endpoint_limit
The account has as many webhook endpoints as it may.
- HTTP status. 409.
- Usual cause. More endpoints created than the account may hold. The contract does not publish the number.
- How to recover. Delete an endpoint you no longer use, then create this one.
- Safe to retry? No. Not until an endpoint is deleted.
- Related. Webhooks
service_unavailable
The request was not processed.
- HTTP status. 503.
- Usual cause. Nothing in your request. The rate limiter or the database could not answer, and the API refuses rather than serve without limits, reads included.
- How to recover. Wait at least the seconds in
Retry-After, then send the same request. - Safe to retry? Yes, after
Retry-After. Nothing was processed. With the same key if the request changes your balance. - Related. Rate limits
internal_error
Something failed on our side. The problem says nothing more about its cause.
- HTTP status. 500.
- Usual cause. Nothing in your request.
- How to recover. Send the same request again. For a request that changes your balance, use the same
Idempotency-Key: a retry with it is always safe. - Safe to retry? Yes, with the same key. A retry with the same key never repeats an operation that went through.
- Related. Idempotency and safe retries
order_limit_exceeded
The order is above the organisation's maximum order amount.
- HTTP status. 422.
- Usual cause. One order larger than the limit set on the account.
- How to recover. Send a smaller order, or ask for the limit to change.
- Safe to retry? No. The same order is refused again.
- Related. Orders and statuses
provider_unavailable
The provider could not answer the lookup. It says nothing about the account.
- HTTP status. 503.
- Usual cause. The provider timed out, failed, or limited the requests Nasfam may send it.
- How to recover. Wait at least the seconds in
Retry-After, then look the recipient up again. Never tell your customer the username is wrong. - Safe to retry? Yes, after
Retry-After. A lookup moves no money. - Related. Recipient lookup
lookup_expired
A quote or an order cites a recipient lookup past its expires_at.
- HTTP status. 409.
- Usual cause. Too long between the lookup and the quote or the order.
- How to recover. Look the recipient up again and show your customer the account again.
- Safe to retry? No. Look up again first. Nothing is held.
- Related. Recipient lookup
recipient_mismatch
The lookup cited no longer matches this request or this account.
- HTTP status. 409.
- Usual cause. Another username, product or selection than the lookup was made for, an account at the username that changed since, or an order citing a lookup its quote was not made from.
- How to recover. Look the recipient up again and show your customer the account again.
- Safe to retry? No. Look up again first. Nothing is held.
- Related. Recipient lookup
recipient_lookup_required
This request must cite a recipient lookup.
- HTTP status. 422.
- Usual cause. A quote or a direct order that cites none, where citing one has been made mandatory.
- How to recover. Look the recipient up, then cite its
idasrecipient_lookup. - Safe to retry? Yes, citing a lookup. The same request without one is refused again.
- Related. Recipient lookup
product_not_permitted
This key may not buy this product. param is /product.
- HTTP status. 403.
- Usual cause. The key was created for some products only, and the request named another.
- How to recover. Use a key allowed this product, or change the products the key may buy in your dashboard.
- Safe to retry? No. The key does not change between attempts.
- Related. Authentication and keys
spending_limit_reached
The order would go over one of your workspace's spending limits. Nothing is charged.
- HTTP status. 422.
- Usual cause. A blocking limit for the order, the day or the month, set in your dashboard. A key with
limits:readalso getslimit: the rule that refused, itswindow, itsproductand itsresets_at. - How to recover. Read
GET /limitsto see what is used. Wait forresets_at, or ask an owner to raise the limit. - Safe to retry? Not until the limit resets or is raised. The same order is refused while the limit is reached.
- Related. Get limits
statement_not_ready
The statement has no file yet: it is still being prepared, or it failed.
- HTTP status. 409.
- Usual cause. A file asked for before the statement's
stateisready. - How to recover. Read
GET /statements/{id}untilstateisready. Afailedstatement never gets a file: request a new one. - Safe to retry? Not until it is ready. Read the statement first.
- Related. Get a statement
ip_not_allowed
This key may be used only from the addresses it lists, and this request came from another. Nothing was read or written.
- HTTP status. 403.
- Usual cause. A key with allowed IP addresses, called from a server or network that is not on its list.
- How to recover. Send the request from one of the key's allowed IP addresses, or add your server's public IP address to the key's Allowed IP addresses in your dashboard.
- Safe to retry? No. Not from this address.
- Related. Authentication and keys
Related guides
- Idempotency and safe retries: how to send a request again safely.
- Sandbox scenarios: how to cause each refusal on purpose.
- Rate limits: backing off.
