Reading the verification API's answers: valid false, 409, 422 and 429

The short answer: in the verification API, a wrong code is not an error: the check answers 200 with valid: false. HTTP errors mean something else: the key (401, 403), the code's status (409), the data (422) or a limit (429). Always decide on error.code and details, never on the message text, which changes with the language.

The answers, one by one

Answer	Means	What to do
201	Code created and sent (or simulated, in the Sandbox)	Keep the id
200 with valid: true	Right code	Carry on
200 with valid: false	Wrong, expired, failed or replaced code	Read status and attempts_left
401	Key missing, invalid, revoked or expired	Check the key or create another
403	The key lacks the permission (insufficient_scope), the IP is not on its list (ip_not_allowed) or SMS is not active (sms_reseller_required)	Fix the key or activate SMS in My MozOut
404	The id does not exist or is not your account’s	Check the id you stored
409	The operation cannot be done in the current state; the reason is in details.reason	For example, resending a code that was already verified: request a new one
422	Invalid data (validation_failed), with the field and reason in details	For example, invalid_number: ask the customer to check the number
429	Too many requests: the API limit, or the code rules you set on the account	Wait the seconds in Retry-After
500, 502, 503	A fault on our side, or the API is switched off	Try later; keep the correlation_id

What an error looks like

Every error has the same shape: error.code (stable, in English, for your program), error.message (for people, in the Accept-Language language), error.correlation_id (the same as the X-Correlation-ID header) and error.details.

Retry or not

1	Worth retrying, after a wait: 429, 500, 502 and 503. If the 429 comes back, wait longer each time.

2	Not worth retrying without changing something: all the others.

3	When sending, retry with the same Idempotency-Key. The same key with the same body returns the stored response and sends no second SMS; with another body, or while the first request is still running, you get 409 (idempotency_conflict). The key stays reserved for 24 hours.

4	When checking, look at the status before retrying with GET /v1/sms/otp/{id}: every check with a wrong code uses an attempt.

Do not show the customer the technical error text. Turn it into a plain sentence: “That number does not look valid”, “Too many codes requested, please try again shortly”. The general API error codes are also in SMS API errors and message statuses.

To ask for help, include the correlation_id, the time and the operation. Never send the key: support does not need it.

Want the full reference for each verification operation? See the API page.

See the API page

Categories

Categories