# Errors

> The error envelope, every documented error code, and whether to retry.

Source page: https://docs.replynodes.com/docs/production/errors

# Errors

Most errors use one JSON envelope (the 402 body is the exception, shown below). Branch on `error.code`, and on `error.next_action.action` when it is present. Do not branch on message text.

```json
{
  "error": {
    "code": "invalid_request",
    "message": "…",
    "request_id": "…"
  }
}
```

| Field | Present | Meaning |
| --- | --- | --- |
| `code` | Always | Stable error code |
| `message` | Always | Human-readable explanation |
| `request_id` | Always (trimmed from the examples below) | Correlation id. Keep it for support |
| `reason` | Some errors | Stable sub-code. A closed set: new values may be added, existing ones are never renamed or removed |
| `retryable` | Some errors | `true` when repeating the identical request later can succeed |
| `next_action` | Where a next step exists | Typed next step for an agent |
| `continuation`, `detail`, `readme`, `status` | Some errors | Extra context |

A `next_action` has `action`, `method`, `url`, `required_fields` and `docs`. It can also have `optional_fields`, `human_message` (a short sentence an agent can show its human), `retry_after_seconds` and `auth`.

## Status codes

| HTTP | Codes | Retry? | What to do |
| ---: | --- | --- | --- |
| 400 | `invalid_request` | No | Fix the request. Compare it with the [API reference](https://docs.replynodes.com/reference). Invalid requests are not charged |
| 401 | `invalid_api_key` and missing or invalid credentials | No | Check the `Authorization: Bearer` header. Rotate or create a key. See [Authentication](https://docs.replynodes.com/docs/auth) |
| 402 | `topup_required` | No | Ask the human to add credits on the billing page. Retry once they confirm |
| 403 | `forbidden_scope`, `verification_required`, `agent_key_not_permitted` | No | The key lacks the scope or is not verified. See [Authentication](https://docs.replynodes.com/docs/auth) |
| 404 | `not_found` | No | The route or resource does not exist. It is not an empty result |
| 405 | `method_not_allowed` | No | Use an allowed method |
| 429 | `rate_limited`, `anonymous_limit_reached`, `restricted_limit_reached`, `poll_rate_limited` | After `Retry-After` | Wait, then retry once. For an anonymous limit, follow `next_action` to get a key |
| 451 | `source_excluded` | No | The publisher excludes automated access |
| 499 | `gateway_timeout` (`client_closed`) | Yes | Your client closed the connection early. Keep it open longer |
| 500 | `internal_error` | Yes | Try again later. Report the `request_id` if it persists |
| 502 | `upstream_unavailable`, `upstream_blocked` | See `retryable` | The source could not be read. Check `reason` and `retryable` |
| 503 | `degraded`, `temporarily_unavailable`, `email_signup_unavailable` | Yes | Try again after `Retry-After`. A dependency is degraded |
| 504 | `gateway_timeout` (`target_timeout`) | Yes | Try again later |

`403 forbidden_scope` is also what an OAuth client gets for a monitor write tool, and what API-key monitor calls get while monitor scope issuance is pending. It is not transient. See [MCP](https://docs.replynodes.com/docs/mcp).

MCP deployments without monitor integration can return `monitor_api_misconfigured` for monitor tool calls. Provider tools keep working.

## Examples

### 429 anonymous_limit_reached

A keyless capability is over its daily limit. The body names the call that gets a key. Trimmed:

```json
{
  "error": {
    "code": "anonymous_limit_reached",
    "message": "The anonymous daily limit has been reached. Get a free API key through the browser-approved claim flow described at https://replynodes.com/auth.md …",
    "next_action": {
      "action": "get_api_key",
      "method": "POST",
      "url": "https://platform.replynodes.com/api/agent/claim",
      "required_fields": [],
      "optional_fields": ["agent_name", "agent_platform", "source"],
      "human_message": "I need a ReplyNodes API key to continue. I'll send you a link: open it, sign in, and approve the request.",
      "docs": "https://replynodes.com/auth.md",
      "retry_after_seconds": 25200
    }
  }
}
```

### 402 topup_required

The workspace has no credits left. This body is top-level (no `error` wrapper), so read `code` and `next_action` directly. Trimmed:

```json
{
  "code": "topup_required",
  "message": "This workspace has no credits left for this request. The API cannot take payment. Ask the human who owns the workspace to open the billing page and choose or manage a plan, then retry once they confirm. Do not retry in a loop.",
  "topup_url": "https://platform.replynodes.com/billing",
  "next_action": {
    "action": "top_up",
    "method": "GET",
    "url": "https://platform.replynodes.com/billing",
    "required_fields": [],
    "human_message": "Your ReplyNodes credits are used up. Please add credits at https://platform.replynodes.com/billing and tell me when you're done.",
    "docs": "https://replynodes.com/auth.md"
  }
}
```

### 502 upstream_unavailable with a reason

The free Markdown endpoint adds `reason` and `retryable` so a program can decide what to do:

```json
{
  "error": {
    "code": "upstream_unavailable",
    "reason": "empty_content",
    "retryable": false,
    "message": "The page was fetched but has no extractable text, …",
    "request_id": "…"
  }
}
```

The full `reason` table is in [Web context](https://docs.replynodes.com/docs/guides/web).

## Retry policy

ReplyNodes does not publish a required retry count. A safe default for reads:

1. Retry only on `retryable: true`, or on `429`, `500`, `503` and `504`, and only for read requests.
2. Wait at least `Retry-After` when it is present. Otherwise use a finite exponential backoff with jitter.
3. Cap the attempts (for example 3) and set a finite timeout on each request.
4. Do not retry `400`, `401`, `402`, `403`, `404` or `451` without changing something.
5. Never retry in a loop on `402`. A human has to add credits.

A retry does not make the underlying data fresher or more complete. If a provider is unavailable, tell downstream agents the data is unavailable instead of inventing an empty success. Log the endpoint, status, elapsed time and `request_id`, and never log credentials or private payloads. See [Operations](https://docs.replynodes.com/docs/production/operations).
