> 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/products/number-verification/reverse-sms/error-codes.md).

# Error codes

{% hint style="info" %}
**Backend API** · Early Access
{% endhint %}

Errors specific to Reverse SMS. Two classes:

* **HTTP-response errors** — returned synchronously on API calls. RFC 7807 body with an `error_code`.
* **Terminal-state error codes** — carried in the ReverseSMSCheck resource body when `status` is `ERROR` or `EXPIRED`.

This page lists only Reverse SMS-specific codes. For the canonical, cross-product error catalogue with full semantics — see the [API Reference](https://docs.idlayr.com/api-reference).

## HTTP-response errors

<table data-header-hidden="false" data-header-sticky><thead><tr><th width="94.390625">HTTP</th><th width="212.31640625">Error code</th><th>When</th></tr></thead><tbody><tr><td>400</td><td><code>phone_number_invalid</code></td><td>The phone number isn't in a valid international format. Use E.164 (e.g. +14155552671).</td></tr><tr><td>400</td><td><code>country_not_supported</code></td><td>The country for the supplied phone number is not supported</td></tr><tr><td>400</td><td><code>bad_request</code></td><td>Malform request body</td></tr><tr><td>400</td><td><code>mno_not_supported</code></td><td>The MNO doesn't support Reverse SMS for this number</td></tr><tr><td>401</td><td><code>unauthorized</code></td><td>Your authentication token is missing, invalid, expired, or couldn't be verified. Get a new token and retry.</td></tr><tr><td>403</td><td><code>invalid_scope</code></td><td>Your credentials are valid but don't have permission for this endpoint or project. Request the correct scope for your token.</td></tr><tr><td>404</td><td><code>check_not_found</code></td><td>No check exists with the supplied <code>check_id</code></td></tr><tr><td>429</td><td><code>too_many_requests</code></td><td>The Project's rate limit has been exceeded.</td></tr></tbody></table>

## Terminal-state error codes

<table><thead><tr><th width="210.6171875">Error Code</th><th width="85.6875">HTTP</th><th>Explanation</th></tr></thead><tbody><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></tr><tr><td>🆕 <code>service_unavailable</code></td><td>503</td><td>We're having a temporary issue on our side.</td></tr><tr><td>🆕 <code>provider_error</code></td><td></td><td>We hit a temporary problem verifying your reply — please try again.</td></tr><tr><td>🆕 <code>sms_not_received</code></td><td></td><td>We didn't receive your verification text in time.</td></tr></tbody></table>

## What this page doesn't cover

Reverse SMS does **not** use an IDlayr SDK, so there are no SDK-class errors to document. If the user cancels the SMS composer or the OS refuses to open the `sms:` URL, that's a platform-level outcome surfaced by your app's own code — not by IDlayr. Treat it as "SMS never sent" and let the check resolve via TTL or your own retry UX.


---

# 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/products/number-verification/reverse-sms/error-codes.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.