400 | invalid_request | The path, query or body did not validate. message says which part, and details.issues lists the problems. | Fix the request using the API Reference. |
400 | account_header_with_key | The request sent Peel-Account with an API key. A key always acts on the account that owns it, and the header works only with a signed-in session. | Drop the header, or use a key of the team’s account. |
400 | execution_run_id_required | Feedback sent with a key limited to one API did not cite a run. | Send the execution_run_id of a run of that API. |
400 | invalid_webhook, invalid_login, invalid_login_site, invalid_execution_job, invalid_execution_answer | The webhook, saved login, execution request or execution answer in the body did not validate. message names the problem. | Fix the body and send it again. |
400 | shape_invalid | Peel-Shape, or a batch item’s shape, is not valid JSON or not a shape Peel accepts. | Send a valid shape, or drop the header. |
400 | version_invalid | Peel-Version is not a version id of one of your APIs, or it was sent on a marketplace call. | Use a version id from GET /v1/apis/{api_id}/revisions, or drop the header. |
400 | invalid_cursor | A list cursor is malformed, or belongs to another list. | Restart from the first page. |
400 | invalid_domain | A site-owner opt-out or notice named a shared suffix such as co.uk or github.io, which no one owner controls. | Name a domain you control. |
400 | keyless_url_credentials | A key or token was sent to /mcp/keyless, which takes none. | Send the key to /mcp instead. |
401 | sign_in_required | A call without an account named a marketplace endpoint that only accounts can call. | Install the API and call it with a key. |
401 | unauthorized | No key, or the key is wrong. | Send a valid key. See Authentication. |
401 | api_key_expired | The key expired. | Create a new key in Settings. |
403 | key_permission_missing | The API key’s access does not cover this route. details.required_permission names what it needs. | Use a key with that access. See Key access. |
403 | key_limited_to_api | The API key is limited to one API and this route, tool or input reaches something else: another API, the account, a marketplace call or a file. It is also refused once that API is deleted. details.api_id names the key’s API. | Use a key for the whole account, or call that API. See Keys for one API. |
403 | key_access_too_wide | A new or rotated key would have more access than the caller. | Ask the owner, or pick narrower access. |
403 | role_permission_missing | Your role on the team does not cover this route. details.role and details.required_permission say which. | Ask an owner or admin. See Teams. |
403 | team_access_denied | The Peel-Account header names a team you are not on. | Pick an account from GET /v1/accounts. |
403 | email_unverified, invite_email_mismatch | Joining a team needs a verified email address, and the invite’s address must be yours. | Verify your email, or ask for an invite to your address. |
403 | sms_requires_paid_plan | A saved login asked for SMS two-factor on the free plan. A Peel phone number needs a paid plan. | Upgrade, or save the login without SMS. |
404 | api_not_found | POST /v1/keys named an api_id that is not on this account. | Pick an API from GET /v1/apis. |
404 | api_key_not_found, connected_app_not_found, login_not_found, schedule_not_found, webhook_not_found, version_not_found, invite_not_found, build_not_found | The key, connected app, saved login, schedule, webhook, API version or team invite named in the request is not on this account. build_not_found is an export of an API that is not on this account. | List them first and use an id from the list. |
404 | endpoint_not_found | A call without an account, or a batch item, named an API or endpoint that does not exist. details.available_endpoints lists the names when Peel knows them. | Use a name from that list. |
404, 410, 400 | invalid_session, expired, not_ready | Device sign-in: the session is unknown, it expired, or the browser has not approved it yet. | Keep polling on not_ready. Otherwise start device sign-in again. |
404 | marketplace_api_removed | A call or batch named a marketplace_id whose listing was taken off the marketplace. Nothing ran and nothing was charged. | Search the marketplace for another listing, or call a copy you installed. |
404 | run_not_found | Feedback named an execution_run_id that is not a run of that API on this account, or a key limited to one API read a run of another API. | Take the run id from that API’s call result or GET /v1/runs. |
404 | not_found | The API, endpoint or other resource does not exist on this account. message says which. For an endpoint, details.available_endpoints lists the published names. | List with GET /v1/apis, or use a name from that list. |
409 | conflict, api_not_ready | The API is not completed, or respond found an API that is not waiting for input. message says which and details.status has the current status. | Poll GET /v1/apis/{api_id}. |
409 | api_not_exportable, missing_endpoints | An export was requested before a version with endpoints exists, or the version uses a retired format. | Wait for completed, or rebuild. |
409 | api_rebuild_required | The version uses a retired format. | POST /v1/apis/{api_id}/rebuild. |
409 | idempotency_key_reused | This Idempotency-Key was already used for a request with a different body. | Send a new key for a new request. |
409 | idempotency_scope_mismatch | This Idempotency-Key was first used by an API key with different access: one limited to another API, or one for the whole account. Nothing ran; in a batch, no item ran. | Send a new key, or retry with the key that made the first request. |
409 | api_deleting | Marketplace install found your earlier install of this API still being deleted. | Try again in a minute. |
409 | team_member_exists, team_full, team_invites_full | The person is already on the team, or the team has no free seat or invite left. | Remove a member or an invite first. |
409 | batch_not_allowed | A batch named an endpoint that is not a public read. | Call signed-in and action endpoints one at a time. |
409 | signups_closed | An access invite was sent while sign-up is closed, so its link would not work. | Open sign-up to invites first. |
409 | api_holds_owner_data | Marketplace publishing found the email address or full name of someone on your account in the API. | Revise or rebuild the API without it, then publish again. |
409 | api_not_publishable | Marketplace publishing needs the API’s current version to come from your own completed build, not a copy, and still linked to its listing. | Rebuild the API, then publish again. |
409 | marketplace_canonical_conflict | Another marketplace API already lists the same site and endpoints, or the listing changed after the expected_marketplace_version_id you sent. | Read the listing again and publish against its current version, or use the listed API. |
409 | marketplace_listing_removed | Publish named a listing that was taken off the marketplace: by Peel, or by its publisher when you are not that publisher. | Use another listing. A publisher relists its own unpublished listing from the same API. |
409 | marketplace_not_publisher | Unpublish named an API that did not publish the listing’s current version: an installed copy, or an API whose contribution someone else replaced. The listing is unchanged. | Unpublish from the API that published it. |
409 | marketplace_direct_call_not_allowed | A call to a marketplace API you have not installed named an endpoint that is not a public data endpoint. | Install the API first. |
409 | proof_not_found, file_proof_unavailable | A site-owner opt-out check did not find the DNS record or file yet, or Peel already refuses to read the domain, so it cannot fetch a file there. | Check again later, or start a new request with the DNS record. |
413 | request_too_large | The body exceeds the route limit. | Send less data. |
422 | invalid_api_descriptor | An export found an endpoint the export format cannot hold, such as an unsupported HTTP method. | Rebuild the API. |
429 | quota_exceeded | Runs, builds, the monthly build budget or the daily cap are used up. details.quota says which (runs, builds, build_budget or daily_runs), and details.reset_at when it resets. Retry-After gives the seconds until then. | Buy a run pack, upgrade, raise the cap, or wait for reset_at. See Plans and limits. |
429 | builds_paused | Peel paused new builds, revisions and rebuilds for everyone after a spike in model spend. Running builds finish and calls keep working. Retry-After gives the seconds until details.resumes_at. | Retry after details.resumes_at. |
409 | not_executable | A call without an account to a marketplace endpoint that uses files, or whose version cannot run. | Install the API and call it with a key. |
429 | try_limit_reached | A call without an account went past the 25 calls a day for its address or the 2,000 a day shared by all such calls. Retry-After gives the seconds until midnight UTC. | Wait for Retry-After, or call with a key. See Call without an account. |
429 | rate_limited | A rate limit. Retry-After gives seconds, and the RateLimit header says which limit. | Wait, then retry. See Plans and limits. |
429 | build_concurrency_limit_reached, daily_build_limit_reached | Your plan’s concurrent builds or the daily build limit, which counts builds started in the last 24 hours. A concurrency refusal sends Retry-After: 30. A daily-limit refusal sets details.reset_at to when the oldest build in the window leaves it, and Retry-After counts the seconds to then. | Wait for a build to finish, or until details.reset_at. |
429 | execution_capacity_exceeded | Interactive execution capacity is full. | Wait, then retry. |
503 | temporarily_unavailable | Peel could not check its rate limits in time: within 250 milliseconds for a call without an account (Retry-After is 30), or within 2 seconds for any other request (Retry-After is 5). Nothing ran. | Wait for Retry-After, then send it again. |
503 | execution_jobs_unavailable, file_store_unavailable, site_logins_unavailable, webhooks_unavailable, device_auth_unavailable | A host service that the request needs is unavailable. | Retry after Retry-After if present. Never assume a write ran. |
402 | payment_required | The route needs a paid plan or more runs, and no more specific code applies. | Check Settings, Billing. |
403 | forbidden | The caller may not do this, and no more specific code applies. | Use an account or key with access. |
405 | method_not_allowed | The path exists but does not take this HTTP method. The Allow header lists the methods it takes. | Use a method from Allow. |
410 | gone | The resource existed and is gone. | Create it again. |
414 | uri_too_long | A path segment in the URL is too long. | Shorten the URL. |
415 | unsupported_media_type | The body’s Content-Type is not one the route reads. | Send application/json. |
422 | unprocessable | The request was well formed but could not be processed. | Read message and fix the request. |
500 | internal_error | An unexpected failure. message is always Internal server error, and instance names the request. | Send it again with the same Idempotency-Key. If it repeats, quote instance. |
502 | bad_gateway | A service behind Peel answered badly. | Retry. |
503 | unavailable | A service Peel needs is down for a moment. | Retry after Retry-After if present. |
504 | timeout | The request took too long. | Retry once. |