> For the complete documentation index, see [llms.txt](https://docs.idlayr.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.idlayr.com/api-reference/errors.md).

# Error Codes

IDlayr APIs return errors as [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem-detail responses (`application/problem+json`). Every problem carries an `error_code` field — a stable, machine-readable identifier — and a `type` URI that resolves to this page, anchored on the same code.

```http
HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json

{
  "type": "https://docs.idlayr.com/api-reference/errors#unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Missing or invalid Access Token.",
  "error_code": "unauthorized"
}
```

The codes below apply across **all** IDlayr v1 products (Eligibility, Secure SNA, Reverse SMS, Discovery, SIM Swap). Product-specific terminal-state codes (carried on the Check resource when `status: ERROR`) live on the per-product error pages — see the [Per-product error catalogues](#per-product-error-catalogues) section at the bottom.

<table data-first-column-sticky><thead><tr><th width="205.35546875">Error Code</th><th width="87.484375">HTTP code</th><th width="280.87890625">Explanation</th><th width="81.33984375">Secure SNA</th><th width="72.625">Discovery</th><th width="78.703125">Reverse-SMS</th><th width="88.23046875">Sim-Swap</th><th width="82.54296875">Eligibility</th></tr></thead><tbody><tr><td><code>unauthorized</code></td><td>401</td><td>Your authentication token is missing, invalid, expired, or couldn't be verified. Get a new token and retry.</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td></tr><tr><td><code>invalid_scope</code></td><td>403</td><td>Your credentials are valid but don't have permission for this endpoint or project. Request the correct scope for your token.</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td></tr><tr><td><code>too_many_requests</code></td><td>429</td><td>The Project's rate limit has been exceeded.</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td></tr><tr><td><code>phone_number_invalid</code></td><td>400</td><td>The phone number isn't in a valid international format. Use E.164 (e.g. +14155552671).</td><td>✅</td><td>❌</td><td>✅</td><td>✅</td><td>✅</td></tr><tr><td><code>not_mobile_ip</code></td><td>412</td><td>This request isn't coming from a mobile data connection, which this check requires.</td><td>✅</td><td>✅</td><td>❌</td><td>✅</td><td>✅</td></tr><tr><td>🆕 <code>invalid_ip</code></td><td>400</td><td>The IP address provided is missing or malformed.</td><td>✅</td><td>✅</td><td>❌</td><td>❌</td><td>✅</td></tr><tr><td><code>bad_request</code></td><td>400</td><td></td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td></tr><tr><td><code>invalid_request</code></td><td>400</td><td></td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td></tr><tr><td><code>mno_not_supported</code></td><td>422</td><td>We don't currently support this mobile operator.</td><td>✅</td><td>✅</td><td>❌</td><td>✅</td><td>❌</td></tr><tr><td>🆕 <code>mno_not_enabled</code></td><td>422</td><td>This mobile operator isn't yet enabled for your project. Check your Approved Networks page, or request approval.</td><td>✅</td><td>✅</td><td>❌</td><td>✅</td><td>❌</td></tr><tr><td>🆕 <code>service_unavailable</code></td><td>503</td><td>We're having a temporary issue on our side.</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td></tr><tr><td><code>mno_server_error</code></td><td>200 (Error field)</td><td>The mobile operator's system returned an unexpected error.</td><td>✅</td><td>✅</td><td>❌</td><td>✅</td><td>❌</td></tr><tr><td><code>mno_timeout</code></td><td>504</td><td>The request to the mobile operator's system timed out.</td><td>✅</td><td>✅</td><td>❌</td><td>✅</td><td>❌</td></tr><tr><td><code>mno_response_error</code></td><td>200 (Error field)</td><td>The mobile operator's system sent back a response we couldn't understand.</td><td>✅</td><td>✅</td><td>❌</td><td>✅</td><td>❌</td></tr><tr><td><code>mno_user_not_found</code></td><td>200 (Error field)</td><td>This phone number isn't recognized by the mobile operator for this check.</td><td>✅</td><td>✅</td><td>❌</td><td>✅</td><td>❌</td></tr><tr><td>🆕 <code>mvno_not_supported</code></td><td>200 (Error field)</td><td>This phone number is from Mobile Virtual Network Operator that is not supported.</td><td>✅</td><td>✅</td><td>❌</td><td>✅</td><td>❌</td></tr><tr><td><code>mno_no_data_available</code></td><td>200 (Error field)</td><td>The mobile operator isn't able to share the information needed for this check.</td><td>✅</td><td>✅</td><td>❌</td><td>✅</td><td>❌</td></tr><tr><td><code>ip_mismatch</code></td><td>200 (Error field)</td><td>Your network connection changed partway through verification. Restart the check on a stable connection.</td><td>✅</td><td>✅</td><td>❌</td><td>❌</td><td>❌</td></tr><tr><td><code>ip_msisdn_mismatch</code></td><td>409</td><td>The phone number doesn't match the mobile network you're currently connected to.</td><td>✅</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td></tr><tr><td><code>internal_error</code></td><td>500</td><td>Something went wrong on our end. Retry, and contact support if it persists.</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td></tr><tr><td><code>check_not_found</code></td><td>404</td><td>We couldn't find a check with this ID — it may be incorrect, expired, or already removed.</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td></tr><tr><td><code>redirect_not_performed</code> / <code>incomplete_redirect</code></td><td>200 (status field)</td><td>The verification wasn't completed in time — the redirect step was never started or never finished.</td><td>✅<br>(Existing on expire check)</td><td>✅<br>(Existing on expire check)</td><td>❌</td><td>❌</td><td>❌</td></tr><tr><td>🆕 <code>provider_error</code></td><td></td><td>We hit a temporary problem verifying your reply — please try again.</td><td>❌</td><td>❌</td><td>✅</td><td>❌</td><td>❌</td></tr><tr><td>🆕 <code>sms_not_received</code></td><td></td><td>We didn't receive your verification text in time.</td><td>❌</td><td>❌</td><td>✅</td><td>❌</td><td>❌</td></tr></tbody></table>

## Per-product error catalogues

Codes specific to a single product — typically terminal-state codes carried on the Check resource when `status: ERROR` — live on the per-product error pages:

* [Eligibility error codes](https://docs.idlayr.com/products/eligibility/error-codes)
* [Secure SNA error codes](https://docs.idlayr.com/products/number-verification/secure-sna/error-codes)
* [Reverse SMS error codes](https://docs.idlayr.com/products/number-verification/reverse-sms/error-codes)
* [Discovery error codes](https://docs.idlayr.com/products/number-verification/discovery/error-codes)
* [SIM Swap error codes](https://docs.idlayr.com/products/risk/sim-swap/error-codes)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.idlayr.com/api-reference/errors.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.