Errors and limits

Every error has the same shape. Read the code: it is the contract. The message is for people and may change.

Response
{
  "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

CodeStatusWhat it means
idempotency_key_required400A POST with no Idempotency-Key header, or a key that starts with a reserved prefix.
invalid_request400The body isn't valid JSON, the request is too large, or a page cursor is wrong.
validation_error400A field is missing or not valid. The fields object says which.
unauthenticated401No key, an unknown key or a revoked key.
member_token_required403A publishable key asked for a member without that member's token, or the token is older than 30 minutes.
not_allowed403This key can't do that here. A secret key sent from a web page on another site gets this.
secret_key_required403This call needs a secret key.
not_found404No such member, reward, transaction or location at this business, or no such route.
method_not_allowed405The route doesn't take this HTTP method.
not_acceptable406The Accept header asks for something other than JSON.
already_reversed409This transaction was already reversed.
idempotency_conflict409This Idempotency-Key was already used with a different body.
unsupported_media_type415The body isn't sent as application/json.
insufficient_balance422The member's balance doesn't cover this redeem.
member_erased422The customer deleted this card.
no_program422The business hasn't set up its card yet.
not_reversible422Only earns and redeems can be reversed.
otp_attempts_exceeded422Too many wrong tries for this code. Send a new one.
otp_expired422The code has expired or was already used. Send a new one.
otp_invalid422The code is wrong. Each code allows 5 tries.
otp_required422This call needs an otp_verification from /v1/otp/verify.
otp_verification_invalid422The otp_verification is wrong, already used, more than 10 minutes old, or for another phone or purpose.
phone_not_supported422Codes go only to Indian numbers (+91) for now.
reward_limit_reached422The reward's limit per member or in total is used up.
reward_unavailable422The reward is switched off or outside its dates.
sandbox_phone_only422The sandbox only takes test numbers: +91 00000 and any five digits.
undo_expired422Not returned by the API. The counter app's own undo, after its 2 minutes.
otp_rate_limited429Too many codes. Wait retry_after seconds.
rate_limited429Too many requests for this key. Wait retry_after seconds.
server_error500Something went wrong on our side. Try again.
otp_send_failed503We couldn't send the code. Nothing was kept, so try again.

Rate limits

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.

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.