Skip to content

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

FieldMeaning
TypetypeThe 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.
TitletitleA short human summary of the status.
StatusstatusThe HTTP status code, repeated in the body.
CodecodeThe stable machine code. Every code is listed below.
CategorycategoryWhat 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.
DetaildetailWhat went wrong, in a sentence for a person. Its wording may change.
ParamparamThe request field at fault, when there is one.
Request IDrequest_idThe 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.

Code for The problem document
A problem
JSON
429 Too Many RequestsSynthetic sandbox data
{  "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 on detail or title. 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 status and category the problem carries.
  • Log request_id with 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.

Code for Rules for every error
POST /v1/ordersSandbox, test key
// 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.

CodeStatusCategorySend the same request again?
invalid_request400validationNo
unknown_field400validationNo
insufficient_scope403authorisationNo
key_environment_mismatch401authenticationNo
insufficient_funds402balanceNot until the balance covers it
quote_expired409validationNo
quote_already_used409validationNo
price_changed409validationNo
duplicate_reference409validationNo
idempotency_key_reused422validationNo
idempotency_in_progress409unknown_outcomeYes, after a short wait
queue_limit429rate_limitYes, later
rate_limited429rate_limitYes, after Retry-After
account_restricted403authorisationNo
capacity_exhausted503providerYes, later
pricing_unavailable503providerYes, later
product_unavailable422authorisationNot until the product is available
recipient_not_found422validationNo
recipient_not_eligible422validationNo
not_found404validationNo
invalid_api_key401authenticationNo
key_expired401authenticationNo
idempotency_key_required400validationYes, with a key
payload_too_large413validationNo
unsupported_media_type415validationNo
browser_request_refused403authenticationNo
webhook_url_refused422webhookNo
endpoint_limit409webhookNo
service_unavailable503internalYes, after Retry-After
internal_error500internalYes, with the same key
order_limit_exceeded422validationNo
provider_unavailable503providerYes, after Retry-After
lookup_expired409validationNo
recipient_mismatch409validationNo
recipient_lookup_required422validationYes, citing a lookup
product_not_permitted403authorisationNo
spending_limit_reached422validationNot until the limit resets or is raised
statement_not_ready409validationNot until it is ready
ip_not_allowed403authorisationNo

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 quantity outside the bounds on GET /products, a months other than 3, 6 or 12, a missing required field, or an Idempotency-Key that 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 quantity and months sent 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 a nbk_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 is held by other orders, or still in pending_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 available is 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 match quote_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_queued on GET /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_status on GET /account shows 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 available false, or a status of planned, on GET /products.
  • How to recover. Read GET /products and order only what is available.
  • Safe to retry? Not until the product is available. Check GET /products first.
  • 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 /sandbox/funding/deposits does not exist on the live host.
  • 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 Bearer followed 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 /orders or POST /sandbox/funding/deposits sent without the header.
  • 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/json media 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 id as recipient_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:read also gets limit: the rule that refused, its window, its product and its resets_at.
  • How to recover. Read GET /limits to see what is used. Wait for resets_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 state is ready.
  • How to recover. Read GET /statements/{id} until state is ready. A failed statement 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