Skip to main content

Idempotency, pagination and limits

Idempotency​

A network can drop an answer after the call succeeded. If you repeat a call that creates a card, you must not get a second card. Idempotency makes that safe: send the same key again, and NAS returns the original result instead of doing the work twice.

Calls that need a key​

CallWhat to send
Create prepaid card, create budget card, and their batch versionsAn Idempotency-Key header (required) and a unique referenceId in the body.
Set card BIN spend controlsAn Idempotency-Key header (required).
Create a wallet, create a tradeAn Idempotency-Key header, and a unique UUID referenceId in the body.
Card and budget transfers in and outA unique clientTransactionId in the body.
Create cardholderA unique referenceId in the body, if you have one.

Rules​

  • Use a new UUID v4 for each new request. Do not reuse a key for a different request.
  • Reuse the same key to retry. Send the same key and the same body after a timeout, a 502 or a 503. You get the original result.
  • Keep a key until the call has finished. Store the key with your own record of the request before you send it, so a restart can retry with the same key.
  • A key is yours alone. Keys of other clients never clash with yours.
  • Do not send the same key twice at the same moment. Wait for the first call to finish before you retry.
curl -X POST "https://sandbox-api.nas.cards/open-api/v3/prepaid-card" \
-H "x-access-token: $ACCESS_TOKEN" \
-H "Idempotency-Key: 6f0a8b0e-3f6a-4c7e-9a1d-2b5c8d7e9f10" \
-H "Content-Type: application/json" \
-d '{"accountId": "<account-id>", "binId": "<bin-id>", "cardMode": "VIRTUAL_CARD", "cardholderId": "<cardholder-id>", "referenceId": "card-0001"}'

A call that only reads data is safe to repeat. So are freeze, unfreeze and delete.

Pagination​

List calls return a page at a time.

ParameterMeaning
limitHow many items to return, from 1 to 100.
pageThe page number. The first page is 1.

Set limit yourself and do not rely on the default.

Every list answer holds the page in list and the full count in total. total can come back as a number or as text, so convert it.

curl "https://sandbox-api.nas.cards/open-api/v3/card-list?accountId=$ACCOUNT_ID&limit=100&page=1" \
-H "x-access-token: $ACCESS_TOKEN"

To read everything, ask for page 1, then 2, and so on, until a page comes back with fewer than limit items, or until you have read total items. Changes made while you read can move items between pages, so de-duplicate on the item id.

Some transaction lists also need a time range. Those have an upper limit on the range, for example three months for budget transactions. Split a longer span into several calls.

Rate limits​

NAS limits how many calls each client can make. The limit is for your client alone, so another client cannot use up your allowance.

  • The allowance is per minute. It refills continuously. A quiet period saves up a full minute's allowance, which you can use in a burst.
  • Your number is in your agreement. Limits are set per client, and they apply in the sandbox too. NAS tells you the limit for your client when it issues credentials.
  • Over the limit. The call is refused with HTTP 429 and code NB42902. The Retry-After header gives the number of seconds to wait. The call was not forwarded, so it is safe to repeat as it was.
Error
{ "code": "NB42902", "message": "request limit reached; retry later", "data": null }

Good habits:

  • Honour Retry-After. Do not retry sooner.
  • Back off with random jitter when many jobs share one client.
  • Prefer webhooks over polling. Poll lists on a schedule, not in a tight loop.
  • Cache your BIN list and your wallet addresses.
  • Use the batch create calls when you issue many cards.

Timeouts and retries together​

  1. Set a client timeout of about 30 seconds.
  2. On a timeout, a 502 or a 503, retry with the same key. Use backoff: 1, 2, 4, 8 seconds, with jitter, up to a few tries.
  3. On 429, wait for Retry-After.
  4. After the last try, record the request as unknown. Read the resource by your own id before you create anything again. See Errors.