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:
{
"success": false,
"messages": [
{
"type": "FAILURE",
"code": "resource_not_found",
"message": "Client not found.",
"httpStatus": "NOT_FOUND",
"technical": false,
"arguments": null
}
],
"data": null
}
| Field | Type | Description |
|---|
success | boolean | true if the operation succeeded |
messages | array | One or more messages describing the outcome |
messages[].type | string | SUCCESS, FAILURE, INFO, or WARNING |
messages[].code | string | null | A machine-readable error code (see below) |
messages[].message | string | null | A human-readable explanation |
messages[].httpStatus | string | The status name mirrored in the body (e.g. BAD_REQUEST) |
messages[].technical | boolean | true for internal/technical messages |
messages[].arguments | object | null | Optional structured context |
data | object | null | The result payload on success; null on failure |
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
| Status | Name | Common cause | How to resolve |
|---|
200 | OK | Request succeeded (the verdict may still be negative) | Inspect data for the outcome |
201 | Created | A resource was created (onboarding, key generation) | Read the new resource from data |
204 | No Content | Success with no body | No action needed |
400 | Bad Request | Missing/invalid fields, malformed JSON, product not enabled, or insufficient/expired balance | Check the messages[].message, your payload, product enablement, and balance |
401 | Unauthorized | X-API-KEY or X-CLIENT-ID missing or invalid | Confirm both headers are present and correct |
404 | Not Found | The resource id or path does not exist | Verify the id and endpoint path |
500 | Internal Server Error | An unexpected error on the platform | Retry with backoff; if it persists, contact support |
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:
| Code | Meaning |
|---|
resource_not_found | The requested resource does not exist |
resource_already_exists | A conflicting resource already exists |
INVALID_MOBILE_NUMBER | The mobile number failed validation |
internal_server_error | An unexpected server error occurred |
401 and may not carry a code — treat any 401 as “fix the X-API-KEY / X-CLIENT-ID headers.”
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
+962791234567 ← Jordan
+971501234567 ← United Arab Emirates
+966512345678 ← Saudi Arabia
0791234567 ← missing country code
+962 79 123 4567 ← contains spaces
+962-79-1234567 ← contains dashes
Retry strategy
Retryable
429 Too Many Requests and 500 Internal Server Error are safe to retry. Use exponential backoff:
- Wait ~1 s after the first failure.
- Double the wait each time: 2 s → 4 s → 8 s …
- Cap retries (e.g. 5 attempts) and the maximum wait (e.g. 60 s).
- 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 support@authmatech.com (Sun–Thu, 09:00–18:00 Amman time). To speed up resolution, include:
- The HTTP status and the
messages[].code / messages[].message from the response.
- The request URL and method.
- The request body (redact your API key).
- The full response body.
- The approximate time of the error, with timezone.