Skip to main content
Peel returns errors in three places: HTTP responses from the host, the error_code inside a call result, and the failure record on a build that did not publish.

Which shape you have

The error envelope

Every route error, except the OAuth and MCP protocol endpoints, has the same fields. It is an RFC 9457 problem document with Peel’s fields beside the standard ones:
  • type is https://docs.peel.sh/errors/ followed by code, which redirects to that code’s row on this page, and title is a fixed summary of that code. status repeats the HTTP status. instance names this request: urn:peel:request: followed by the request id that the x-request-id header also carries. Quote it when you contact support.
  • code is a stable snake_case string. Branch on it, not on message.
  • retryable is true when the same request can succeed later, such as on 429 and 503. Wait for Retry-After when it is set.
  • retry says the same thing as a class: same_key when retryable is true, fix_request when it is not. See Repeating a failed call.
  • details holds anything else the error carries, such as validation issues.
The response is application/problem+json when your Accept header names that type, and application/json otherwise. The body is the same either way. These responses carry Vary: Accept, so a cache keeps the two apart. OAuth endpoints return the standard OAuth error and error_description fields. MCP returns JSON-RPC errors. A :call that ran the program answers with the call envelope instead, because its status field is the call’s outcome (success or error), not a number.

HTTP errors

MCP tool errors carry the same code in the JSON-RPC error’s data. Two codes come only from MCP tools: invalid_execution_tool_arguments, when a tool’s arguments did not validate (details.issues lists the problems), and api_key_required, a tool result with isError set when call_read_route is called with a sign-in token. That tool runs as your API key, so connect with one.

Codes from executions, files, logins and billing

An error with no more specific code gets the code of its status: invalid_request (400), unauthorized (401), payment_required (402), forbidden (403), not_found (404), method_not_allowed (405), conflict (409), gone (410), request_too_large (413), uri_too_long (414), unsupported_media_type (415), unprocessable (422), rate_limited (429), internal_error (500), bad_gateway (502), unavailable (503) and timeout (504). A 429 or 5xx is retryable: send it again with the same Idempotency-Key. If a 5xx repeats, quote instance to kaan@peel.sh.

Call errors

Inside a call result, error_code is a stable string, repeated in code. The HTTP status mirrors status_code. Write-specific and session codes are in Signed-in and action endpoints. A failed call, as production answered on 18 November for {"limit": 2} sent to an endpoint that takes no inputs. The full response also carries data, error, execution_time and the other call fields.

Repeating a failed call

Every failed call says what it changed and how it may be sent again. Read both fields before you retry, and never retry a write on the HTTP status alone. retry_safe is false exactly when action_outcome is committed or unknown. A request answered with the error envelope did not commit a write, and its retry is same_key or fix_request. Interactive executions carry the same fields on error and on a failed result. MCP puts them in the JSON-RPC error’s data. A write that failed under an Idempotency-Key stays unknown when that key is sent again, unless the first attempt never started.

Build failures

GET /v1/apis/{api_id} returns api.status: "failed" with a structured failure. The same failure appears on GET /v1/apis/{api_id}/health when status is build_failed.
Use failure.code for branching, failure.recommended_action for what to do and failure.support_debug_id when you contact support.

Failure reason codes

recommended_action is one of contact_support, revise_task, retry_later, try_different_url or wait_or_rebuild. failure.category groups codes into access_policy, auth_required, build_timeout, compile_quality, infrastructure, planner_failure and unknown. failure.refund_reviewable says whether the charge can be reviewed. A failed build keeps its diagnostics; Peel never hides a verification failure behind a fallback.

When an error means rebuild

Rebuild when health reports recommended_action: "rebuild", when a previously healthy endpoint starts returning output_schema_mismatch, invalid_upstream_json or endpoint_not_found, or when several endpoints on one API fail in a short window. See API updates.