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.
{
"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. 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 |
| 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 |
| 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.
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:
{
"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:
{
"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:
{
"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.
Retry policy
ReplyNodes does not publish a required retry count. A safe default for reads:
- Retry only on
retryable: true, or on429,500,503and504, and only for read requests. - Wait at least
Retry-Afterwhen it is present. Otherwise use a finite exponential backoff with jitter. - Cap the attempts (for example 3) and set a finite timeout on each request.
- Do not retry
400,401,402,403,404or451without changing something. - 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.