API Errors & Status Codes - Authmatech

Every Authmatech response uses the same envelope. This page is a concise reference; for retry strategy and a debugging checklist, see the full Errors & responses guide.

Envelope

{
  "success": false,
  "messages": [
    { "type": "FAILURE", "code": "resource_not_found", "message": "Client not found.", "httpStatus": "NOT_FOUND", "technical": false, "arguments": null }
  ],
  "data": null
}

Read results from data. Treat success: false or a non‑200 status as an error.

Status codes

Status	Meaning	Retryable
`200`	OK (verdict may still be negative)	—
`201`	Created	—
`204`	No Content	—
`400`	Bad Request — validation, product not enabled, or balance issue	No
`401`	Unauthorized — bad/missing `X-API-KEY` or `X-CLIENT-ID`	No
`404`	Not Found	No
`429`	Too Many Requests	Yes (backoff)
`500`	Internal Server Error	Yes (backoff)

Error codes

Code	Meaning
`resource_not_found`	The resource does not exist
`resource_already_exists`	A conflicting resource exists
`INVALID_MOBILE_NUMBER`	The mobile number failed validation
`internal_server_error`	Unexpected server error

A 200 with data.validNumber: false (or a BLOCK decision) is a successful call with a negative business outcome — not an error. Branch on data, not just the status code.

See Errors & responses for retry strategy, E.164 rules, and the debugging checklist, and Rate limits for 429 handling.