Skip to main content
Every Authmatech API call — success or failure — returns the same JSON envelope. Understanding it, and the status codes that accompany it, lets you build resilient integrations and resolve issues quickly.

​
The response envelope

Authmatech does not return a bare { error: ... } object. Instead, every response is wrapped consistently:
A negative business outcome is not an error. A verification that returns {"success": true, "data": {"validNumber": false}} is a successful 200 call with a negative verdict. Branch your logic on data; reserve error handling for success: false and non‑200 status codes.

​
HTTP status codes

Validation, product-enablement, and balance problems all surface as 400 Bad Request with a descriptive message. Always read messages[].message rather than relying on the status code alone.

​
Error codes

The code field carries a stable, machine-readable identifier you can branch on. Common values include: Authentication failures are returned as 401 and may not carry a code — treat any 401 as “fix the X-API-KEY / X-CLIENT-ID headers.”

​
Phone number format

Submit mobile numbers in E.164 format: a leading +, the full country code (no leading zero), and the subscriber number with no spaces, dashes, or parentheses. Valid
Invalid

​
Retry strategy

​
Retryable

429 Too Many Requests and 500 Internal Server Error are safe to retry. Use exponential backoff:
  1. Wait ~1 s after the first failure.
  2. Double the wait each time: 2 s → 4 s → 8 s …
  3. Cap retries (e.g. 5 attempts) and the maximum wait (e.g. 60 s).
  4. Add small random jitter (±100 ms) so clients don’t retry in lockstep.
See Rate limits for guidance on 429.

​
Non-retryable

400, 401, and 404 reflect problems in the request itself. Retrying unchanged returns the same result — read messages[].message and fix the cause first.

​
Debugging checklist

Authentication (401)
  • Are both X-API-KEY and X-CLIENT-ID present on every request?
  • Did you copy the API key without trailing whitespace or quotes?
  • Are you using the right credentials for the environment (sandbox vs. production)?
Request body (400)
  • Is Content-Type: application/json set and does the JSON parse cleanly?
  • Are all required fields present for the endpoint?
  • Are mobile numbers in E.164 format?
  • Is the product enabled and the balance sufficient and unexpired?
Not found (404)
  • Is the resource id correct and from the same environment?

​
Getting help

If you’re still stuck after the checklist, contact connect@authmatech.com (Sun–Thu, 09:00–18:00 Amman time). To speed up resolution, include:
  1. The HTTP status and the messages[].code / messages[].message from the response.
  2. The request URL and method.
  3. The request body (redact your API key).
  4. The full response body.
  5. The approximate time of the error, with timezone.