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
| Call | What to send |
|---|---|
| Create prepaid card, create budget card, and their batch versions | An Idempotency-Key header (required) and a unique referenceId in the body. |
| Set card BIN spend controls | An Idempotency-Key header (required). |
| Create a wallet, create a trade | An Idempotency-Key header, and a unique UUID referenceId in the body. |
| Card and budget transfers in and out | A unique clientTransactionId in the body. |
| Create cardholder | A 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
502or a503. 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.
| Parameter | Meaning |
|---|---|
limit | How many items to return, from 1 to 100. |
page | The 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
429and codeNB42902. TheRetry-Afterheader gives the number of seconds to wait. The call was not forwarded, so it is safe to repeat as it was.
{ "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
- Set a client timeout of about 30 seconds.
- On a timeout, a
502or a503, retry with the same key. Use backoff: 1, 2, 4, 8 seconds, with jitter, up to a few tries. - On
429, wait forRetry-After. - After the last try, record the request as unknown. Read the resource by your own id before you create anything again. See Errors.