ReplyNodes
Production

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": "…"
  }
}
FieldPresentMeaning
codeAlwaysStable error code
messageAlwaysHuman-readable explanation
request_idAlways (trimmed from the examples below)Correlation id. Keep it for support
reasonSome errorsStable sub-code. A closed set: new values may be added, existing ones are never renamed or removed
retryableSome errorstrue when repeating the identical request later can succeed
next_actionWhere a next step existsTyped next step for an agent
continuation, detail, readme, statusSome errorsExtra 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

HTTPCodesRetry?What to do
400invalid_requestNoFix the request. Compare it with the API reference. Invalid requests are not charged
401invalid_api_key and missing or invalid credentialsNoCheck the Authorization: Bearer header. Rotate or create a key. See Authentication
402topup_requiredNoAsk the human to add credits on the billing page. Retry once they confirm
403forbidden_scope, verification_required, agent_key_not_permittedNoThe key lacks the scope or is not verified. See Authentication
404not_foundNoThe route or resource does not exist. It is not an empty result
405method_not_allowedNoUse an allowed method
429rate_limited, anonymous_limit_reached, restricted_limit_reached, poll_rate_limitedAfter Retry-AfterWait, then retry once. For an anonymous limit, follow next_action to get a key
451source_excludedNoThe publisher excludes automated access
499gateway_timeout (client_closed)YesYour client closed the connection early. Keep it open longer
500internal_errorYesTry again later. Report the request_id if it persists
502upstream_unavailable, upstream_blockedSee retryableThe source could not be read. Check reason and retryable
503degraded, temporarily_unavailable, email_signup_unavailableYesTry again after Retry-After. A dependency is degraded
504gateway_timeout (target_timeout)YesTry 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:

  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.

On this page