Errors and limits
Every error has the same shape. Read the code: it is the contract. The message is for people and may change.
{
"error": {
"code": "otp_rate_limited",
"message": "Too many codes sent. Try again in 58 minutes.",
"retry_after": 3480
}
}
A validation_error adds fields, naming each field that is wrong. Every 429 adds retry_after, the seconds to wait, also sent as the Retry-After header.
Codes
| Code | Status | What it means |
|---|---|---|
idempotency_key_required | 400 | A POST with no Idempotency-Key header, or a key that starts with a reserved prefix. |
invalid_request | 400 | The body isn't valid JSON, the request is too large, or a page cursor is wrong. |
validation_error | 400 | A field is missing or not valid. The fields object says which. |
unauthenticated | 401 | No key, an unknown key or a revoked key. |
member_token_required | 403 | A publishable key asked for a member without that member's token, or the token is older than 30 minutes. |
not_allowed | 403 | This key can't do that here. A secret key sent from a web page on another site gets this. |
secret_key_required | 403 | This call needs a secret key. |
not_found | 404 | No such member, reward, transaction or location at this business, or no such route. |
method_not_allowed | 405 | The route doesn't take this HTTP method. |
not_acceptable | 406 | The Accept header asks for something other than JSON. |
already_reversed | 409 | This transaction was already reversed. |
idempotency_conflict | 409 | This Idempotency-Key was already used with a different body. |
unsupported_media_type | 415 | The body isn't sent as application/json. |
insufficient_balance | 422 | The member's balance doesn't cover this redeem. |
member_erased | 422 | The customer deleted this card. |
no_program | 422 | The business hasn't set up its card yet. |
not_reversible | 422 | Only earns and redeems can be reversed. |
otp_attempts_exceeded | 422 | Too many wrong tries for this code. Send a new one. |
otp_expired | 422 | The code has expired or was already used. Send a new one. |
otp_invalid | 422 | The code is wrong. Each code allows 5 tries. |
otp_required | 422 | This call needs an otp_verification from /v1/otp/verify. |
otp_verification_invalid | 422 | The otp_verification is wrong, already used, more than 10 minutes old, or for another phone or purpose. |
phone_not_supported | 422 | Codes go only to Indian numbers (+91) for now. |
reward_limit_reached | 422 | The reward's limit per member or in total is used up. |
reward_unavailable | 422 | The reward is switched off or outside its dates. |
sandbox_phone_only | 422 | The sandbox only takes test numbers: +91 00000 and any five digits. |
undo_expired | 422 | Not returned by the API. The counter app's own undo, after its 2 minutes. |
otp_rate_limited | 429 | Too many codes. Wait retry_after seconds. |
rate_limited | 429 | Too many requests for this key. Wait retry_after seconds. |
server_error | 500 | Something went wrong on our side. Try again. |
otp_send_failed | 503 | We couldn't send the code. Nothing was kept, so try again. |
Rate limits
- Secret key: 600 a minute.
- Publishable key: 600 a minute, and 30 a minute from one IP address.
Code limits
Codes go only to Indian numbers (+91); others get phone_not_supported. A code is valid for 5 minutes and allows 5 tries. The token from a right code is valid for 10 minutes and works once.
- For one shop, phone and purpose: one code every 45 seconds, and 5 an hour and 10 a day.
- For one phone across every shop: 20 an hour and 50 a day through secret keys, and the same again through publishable keys.
- Through publishable keys only: 30 an hour and 100 a day for one IP address, and 100 an hour and 500 a day for one shop.
- Through secret keys and the counter app together: 100 codes a day for a new shop (and 1,000 for all new shops together), and 2,000 once Nimbuu has checked the shop. Automated messages have a daily limit of the same size, counted apart.
Only codes that are sent count. A refused call or a failed send uses up nothing. Every code limit answers 429 otp_rate_limited. In the sandbox there are no code limits.