---
title: Errors — Reference
description: Stable HTTP status codes + machine-readable error codes in the JSON body.
url: https://agentnumber.really.com/docs/reference/errors
doc_version: "1.0.0"
last_updated: "2026-05-15"
---

> ## Documentation index
> Fetch the complete documentation index at: https://agentnumber.really.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Stable HTTP status codes + machine-readable error codes in the JSON body. Switch on the `error` field, not on English strings — the prose is for humans, the code is the contract.

## Response shape

```json
{
  "error": "stable_machine_code",
  "message": "Free-form human diagnostic. Do not parse."
}
```

## HTTP status codes you should expect

| Status | Class | What it means |
| --- | --- | --- |
| `200` | Success | Request succeeded; body has the payload. |
| `400` | Client | Body or query string is malformed. |
| `401` | Auth | Missing, invalid, revoked, or expired bearer token. |
| `402` | Payment | Payment required. Body carries the challenge. |
| `403` | Auth | Token is valid but doesn't own the resource you're touching. |
| `404` | Client | Path or referenced ID doesn't exist. |
| `409` | Conflict | State conflict (e.g. number already on a call). |
| `500` | Server | Internal error. Retry transparently — usually transient. |
| `502` | Server | Hardware-side error. Retry. |
| `503` | Server | Capacity issue (pool exhausted, hardware busy). Retry with backoff. |

## Common error codes

| Code | HTTP | Where |
| --- | --- | --- |
| `invalid_request` | 400 | Body / query missing required fields |
| `unauthorized` | 401 | Bearer missing or invalid |
| `signature_mismatch` | 401 | Auth recovery: signature didn't recover the claimed wallet |
| `nonce_invalid` | 401 | Auth recovery: nonce expired, used, or unknown |
| `no_active_subscription` | 402 | Wallet has no active subscription |
| `pool_exhausted` | 503 | No phone numbers currently free |
| `phone_node_error` | 502 | Upstream hardware unreachable |

## Retry strategy

- **5xx + 502** → retry with exponential backoff. These are transient.
- **503 `pool_exhausted`** → join [/waitlist](/docs/reference/waitlist) instead of busy-looping.
- **401** → don't retry blindly. The token is dead; recover it via [Auth](/docs/auth).
- **402** → expected on first `/subscribe`. Read the challenge, sign, retry once.

## Sitemap

- [Overview](/docs/)
- [Quickstart](/docs/quickstart)
- [Authentication](/docs/auth)
- [SMS](/docs/sms)
- [Voice](/docs/voice)
- [MCP](/docs/mcp)
- [Payment](/docs/payment)

See the full [sitemap.md](/sitemap.md) for the complete index of docs pages.

---

← Previous: [Reference](/docs/#api-reference) · Next: [Rate limits](/docs/reference/rate-limits) →