> ## Documentation Index > Fetch the complete documentation index at: https://docs.pomerado.ai/llms.txt > Use this file to discover all available pages before exploring further. # Errors > The error envelope every REST, Dashboard and MCP error shares, and every error code. Every error from the REST API, the Dashboard and MCP tools has the same shape: ```json theme={null} { "error": { "code": "invalid_input", "message": "The input does not match this tool's input schema, so no job was started. issues names each field's path and what it expects. Fix the input and call again.", "retryable": false, "docs_url": "https://docs.pomerado.ai/errors#invalid_input", "details": { "issues": [{ "path": "/departure_date", "message": "must be string" }] } } } ``` * `code` is one of the codes below. Codes are stable; branch on `code`, never on `message`. * `message` says what happened and what to do. It names the API's routes on REST and the MCP tools on MCP. * `retryable` is `true` when the same request can succeed later. * `docs_url` links to the code's section on this page. * `details` carries the fields listed for the code, and is otherwise empty. An MCP tool error carries the same object as its result text, plus `retry_after_seconds` when it is retryable. A write sent without a `retry_key` whose code may follow an accepted write instead has `retryable: false` and `write_possibly_accepted: true`: check the job before repeating it, because a repeat without the key is a new website action. A run that settles without a result returns a receipt with `kind: "error"` and this same object in `error`, beside its `job_id`, `effect` and `output`. ## invalid\_request The request is malformed: its body, query or a field does not match what this endpoint accepts. * HTTP status: `400` * Retry: After changing the request. **What to do:** Fix the request and send it again; details.issues, when present, says where. | `details` field | Meaning | | - | - | | `issues` | When present, each failing part: `path`, its JSON pointer under `/path`, `/query`, `/headers` or `/body`, and `message`, what is expected there. Never the value sent. | ## invalid\_answer These answers do not fit the pending request. * HTTP status: `400` * Retry: After changing the request. **What to do:** Answer every question once, with an offered option id where it lists options, and send the answers again with POST /v1/jobs/{id}/input. question\_id and reason name the first problem. | `details` field | Meaning | | - | - | | `question_id` | The question whose answer failed, when one did. | | `reason` | Why: `missing_answer`, `unexpected_answer`, `malformed`, `unoffered_option`, `other_not_allowed`, `selection_bounds`, `too_long`, `username_not_allowed` or `password_required`. | ## invalid\_input The input does not match this tool's input schema, so no job was started. * HTTP status: `400` * Retry: After changing the request. **What to do:** issues names each field's path and what it expects. Fix the input and call again. | `details` field | Meaning | | - | - | | `issues` | Each failing field: `path`, its JSON pointer, and `message`, what the schema expects there. Never the value sent. | ## input\_rejected The tool or the website refused a value in the input after the run started. * HTTP status: `409` * Retry: After changing the request. **What to do:** Correct the input and run it again with a new retry key. Unless possible\_commit is true, nothing changed on the website; if it is, check the website first. | `details` field | Meaning | | - | - | | `possible_commit` | Whether a step may already have changed the website. | | `reason` | What the run said about the refusal, with the tool's own reason when it gave one. | ## unsupported\_login\_field This tool's sign-in does not take one of the login fields sent. * HTTP status: `400` * Retry: After changing the request. **What to do:** The tool's login\_fields and sign\_in\_methods list what it takes. Call again without field. | `details` field | Meaning | | - | - | | `field` | The login field the tool's sign-in does not take. | ## effect\_required A website build requires effect. * HTTP status: `400` * Retry: After changing the request. **What to do:** Use read when the tool only looks things up. Use write when it changes anything on the site: filling in or advancing a form that saves data (an application, profile or checkout), submitting, booking, drafts, holds, uploads and account updates. A search, filter or query form is a read. Use ask when unsure: the build first asks read or write, as a pending input request answered with POST /v1/jobs/{id}/input. ## invalid\_email The email address does not match the signed-in account's. * HTTP status: `400` * Retry: After changing the request. **What to do:** Type the account's email address exactly to confirm. ## request\_too\_large The request body is larger than this endpoint accepts. * HTTP status: `413` * Retry: After changing the request. **What to do:** Send a smaller request. ## method\_not\_allowed This endpoint does not accept that HTTP method. * HTTP status: `405` * Retry: No. Repeating the request does not help. **What to do:** Use a method the endpoint documents. ## not\_found Nothing with that ID exists, or this caller may not see it. * HTTP status: `404` * Retry: No. Repeating the request does not help. **What to do:** Check the ID, and that this caller's account and permissions cover it. ## unauthorized The request's credentials were missing, expired or rejected. * HTTP status: `401` * Retry: After signing in again. **What to do:** Sign in again, or send a valid API key or access token. ## session\_refresh\_required The Dashboard session needs to be refreshed. * HTTP status: `401` * Retry: After signing in again. **What to do:** Refresh the session and repeat the request. ## reauthentication\_required This action needs a recent sign-in. * HTTP status: `401` * Retry: After signing in again. **What to do:** Sign in again, then repeat it. ## forbidden This caller's account, grant or permissions do not allow this request. * HTTP status: `403` * Retry: No. Repeating the request does not help. **What to do:** Check the account's state and the permissions granted to this client or key. ## stale\_grant The grant changed since it was read. * HTTP status: `409` * Retry: After changing the request. **What to do:** Read the grant again and send the change with its current revision. ## save\_forbidden This client may not save website logins: saving needs the credentials:manage permission. * HTTP status: `403` * Retry: After changing the request. **What to do:** Call again without save, or ask the user to grant credentials:manage. | `details` field | Meaning | | - | - | | `reason` | Why, when known: `account_lacks_manage`, `consent_lacks_manage`, `grant_lacks_manage` or `grant_inactive`. | ## account\_unsupported This account type does not offer this action. * HTTP status: `403` * Retry: No. Repeating the request does not help. **What to do:** Use a Personal account owner for Personal features; the service tier has no self-service billing. ## organization\_access\_removed This user's membership in the Business account has ended. * HTTP status: `403` * Retry: No. Repeating the request does not help. **What to do:** Ask an administrator of the organization to restore access. ## account\_deletion\_pending This account is being deleted. * HTTP status: `403` * Retry: No. Repeating the request does not help. **What to do:** Nothing more can be done with it. ## sign\_in\_required This needs a signed-in Pomerado account. * HTTP status: `401` * Retry: After signing in again. **What to do:** Where device sign-in is enabled, start one (the sign\_in tool on MCP, POST /v1/sign-in on REST) and give the person its verification\_url and user\_code; they sign in on any device and approve, and polling then returns an API key to send as an Authorization: Bearer header. Otherwise sign in with OAuth (connect or re-authenticate this server in your MCP client), or create an API key on the API keys page in the Pomerado Dashboard and send it as an Authorization: Bearer header. ## try\_limit\_reached Pomerado's keyless runs are used up for today from this network or across Pomerado. * HTTP status: `429` * Retry: Yes. Repeat the same request, with its retry key, after a short wait. **What to do:** Sign in for the free plan's limits (the sign\_in tool on MCP, POST /v1/sign-in on REST), or send the same request again after retry\_after\_seconds. ## try\_tier\_unavailable Keyless use is unavailable right now. * HTTP status: `503` * Retry: No. Repeating the request does not help. **What to do:** Sign in to continue: sign in with OAuth (connect or re-authenticate this server in your MCP client), or create an API key on the API keys page in the Pomerado Dashboard and send it as an Authorization: Bearer header. ## sign\_in\_limit\_reached Too many device sign-ins were started from this network today. * HTTP status: `429` * Retry: Yes. Repeat the same request, with its retry key, after a short wait. **What to do:** Finish one already started, start another after retry\_after\_seconds, or sign in with OAuth (connect or re-authenticate this server in your MCP client), or create an API key on the API keys page in the Pomerado Dashboard and send it as an Authorization: Bearer header. ## sign\_in\_unavailable Device sign-in isn't available here. * HTTP status: `503` * Retry: No. Repeating the request does not help. **What to do:** Instead, sign in with OAuth (connect or re-authenticate this server in your MCP client), or create an API key on the API keys page in the Pomerado Dashboard and send it as an Authorization: Bearer header. ## access\_denied The person declined this device sign-in. * HTTP status: `410` * Retry: No. Repeating the request does not help. **What to do:** Start a new sign-in only if they ask to connect this agent again. ## expired\_token This device sign-in expired, or its API key was already handed out. * HTTP status: `410` * Retry: No. Repeating the request does not help. **What to do:** Start a new sign-in, and poll it until the person approves. ## account\_selection\_required Several saved logins for this website are available to this caller. * HTTP status: `409` * Retry: After changing the request. **What to do:** Call again with connected\_account\_id set to the login to use. ## saved\_login\_conflict This website already has a saved login for a different username, and a saved login comes before credentials in the request. * HTTP status: `409` * Retry: After changing the request. **What to do:** Remove or replace that saved login with PATCH /v1/connections/{id}, or call again with connected\_account\_id to use it. | `details` field | Meaning | | - | - | | `site` | The website's registrable domain, for example `example.com`. | | `masked_username` | The saved login's username, masked to its first and last two characters. | | `first_verified_at` | When the saved login first signed in successfully (ISO 8601). | ## login\_identity\_conflict This account's login for the website is locked to a different username. * HTTP status: `409` * Retry: After changing the request. **What to do:** Use that login, or correct the saved login on the Logins page in the Pomerado Dashboard. | `details` field | Meaning | | - | - | | `site` | The website's registrable domain, for example `example.com`. | | `masked_username` | The saved login's username, masked to its first and last two characters. | | `first_verified_at` | When the saved login first signed in successfully (ISO 8601). | ## site\_login\_exists A login for this website is already saved, and this account keeps one per website. * HTTP status: `409` * Retry: After changing the request. **What to do:** Send it again without saving, or change the saved login with PATCH /v1/connections/{id}. ## legacy\_duplicate\_saved\_logins This account has more than one saved login for the website from before the one-login rule. * HTTP status: `409` * Retry: After changing the request. **What to do:** Delete the extra logins with DELETE /v1/connections/{id}, then try again. ## saved\_login\_unsettled A change to this website's saved login is still being confirmed. * HTTP status: `409` * Retry: Yes. Repeat the same request, with its retry key, after a short wait. **What to do:** Wait a moment and send the same request again. ## login\_in\_use This saved login is in use by a running job. * HTTP status: `409` * Retry: Yes. Repeat the same request, with its retry key, after a short wait. **What to do:** Wait for the job to finish, then try again. ## login\_save\_in\_progress A save of this website's login is still in progress. * HTTP status: `409` * Retry: Yes. Repeat the same request, with its retry key, after a short wait. **What to do:** Wait for it to finish, then read the saved logins with GET /v1/connections. ## invalid\_credential The login's values are not valid for a saved login. * HTTP status: `422` * Retry: After changing the request. **What to do:** Correct the username, password or other fields and save it again. ## authenticator\_not\_configured This saved login has no authenticator secret. * HTTP status: `404` * Retry: No. Repeating the request does not help. **What to do:** Add the authenticator secret to the login on the Logins page in the Pomerado Dashboard first. ## credentials\_rejected The website rejected the login. * HTTP status: `409` * Retry: After changing the request. **What to do:** Correct the login before running the tool again. | `details` field | Meaning | | - | - | | `field` | The login field the website rejected, when it said which. | | `possible_commit` | Whether a step may already have changed the website. | ## pin\_required Saved logins are locked. * HTTP status: `403` * Retry: No. Repeating the request does not help. **What to do:** Unlock them with the Logins PIN on the Logins page in the Pomerado Dashboard. ## pin\_not\_set No Logins PIN is set for this account. * HTTP status: `403` * Retry: No. Repeating the request does not help. **What to do:** Set one on the Logins page in the Pomerado Dashboard. ## pin\_already\_set This account already has a Logins PIN. * HTTP status: `409` * Retry: No. Repeating the request does not help. **What to do:** Change it or reset it instead. ## invalid\_pin The PIN is not in the accepted format. * HTTP status: `400` * Retry: After changing the request. **What to do:** Use the number of digits the form asks for. ## pin\_mismatch The two PINs do not match. * HTTP status: `400` * Retry: After changing the request. **What to do:** Type the same PIN twice. ## wrong\_pin The PIN is incorrect. * HTTP status: `403` * Retry: After changing the request. **What to do:** Try again; repeated wrong PINs lock unlocking for a while. ## pin\_throttled Too many PIN attempts. * HTTP status: `429` * Retry: No. Repeating the request does not help. **What to do:** Wait before trying again, or reset the PIN after signing in again. ## sms\_number\_not\_allowed Pomerado phone numbers aren't available to this account yet. * HTTP status: `403` * Retry: No. Repeating the request does not help. **What to do:** Not every account may assign one yet. ## sms\_number\_not\_linked This saved login has no Pomerado phone number. * HTTP status: `404` * Retry: No. Repeating the request does not help. **What to do:** Assign one first. ## sms\_number\_cap\_reached Pomerado has no more phone numbers to give out right now. * HTTP status: `503` * Retry: Yes. Repeat the same request, with its retry key, after a short wait. **What to do:** Try again later. ## sms\_number\_purchase\_failed Pomerado could not get a phone number for this login. * HTTP status: `503` * Retry: Yes. Repeat the same request, with its retry key, after a short wait. **What to do:** Try again in a few minutes. ## site\_not\_supported Pomerado doesn't build tools for this website. * HTTP status: `403` * Retry: No. Repeating the request does not help. **What to do:** Calling again does not help. Tools you already have for the site keep running. | `details` field | Meaning | | - | - | | `site` | The refused site's registrable domain. | | `category` | Why it is refused: `ticket_site`, `bank` or `government`. | ## quota\_exceeded The account's quota is used up. * HTTP status: `429` * Retry: Only as a fresh request with a new retry key. **What to do:** Wait for the reset or upgrade on the billing settings in the Pomerado Dashboard, then send a fresh request with a new retry key. | `details` field | Meaning | | - | - | | `reset_at` | When the quota resets (ISO 8601), when known. | ## quota\_expired The quota reservation for this request expired before it was accepted. * HTTP status: `409` * Retry: Only as a fresh request with a new retry key. **What to do:** Confirm no job was accepted with GET /v1/jobs/{id}, then send a fresh request with a new retry key. ## website\_pending Another build for this website is pending. * HTTP status: `409` * Retry: Only as a fresh request with a new retry key. **What to do:** Check that build with GET /v1/jobs/{id}, then use a new retry key if another build is still needed. ## retry\_conflict This retry key was already used for a different request. * HTTP status: `409` * Retry: Only as a fresh request with a new retry key. **What to do:** Repeat the original request with that key, or use a new key for a new request. ## execution\_budget\_exhausted This job used its whole execution budget. * HTTP status: `409` * Retry: No. Repeating the request does not help. **What to do:** Check the job's outcome with GET /v1/jobs/{id} before starting another. ## input\_expired This input request has expired. * HTTP status: `410` * Retry: No. Repeating the request does not help. **What to do:** Read the job again with GET /v1/jobs/{id}. ## input\_not\_pending This job has no such pending input request. * HTTP status: `409` * Retry: After changing the request. **What to do:** Read the job again with GET /v1/jobs/{id} and answer its current request\_id and request\_version. ## input\_declined The client declined the input request; it stays pending. * HTTP status: `409` * Retry: No. Repeating the request does not help. **What to do:** Answer it, or cancel the job with POST /v1/jobs/{id}/cancel. ## input\_cancelled The client cancelled the input request; it stays pending. * HTTP status: `409` * Retry: No. Repeating the request does not help. **What to do:** Answer it, or cancel the job with POST /v1/jobs/{id}/cancel. ## result\_expired This job's result is no longer kept: Pomerado keeps a result only until it is first read, and at most 5 minutes after the job ends. * HTTP status: `410` * Retry: No. Repeating the request does not help. **What to do:** Check the website before starting the work again; a new run may act on it again. ## result\_unavailable The job was accepted, but its result could not be read. * HTTP status: `503` * Retry: No. Repeating the request does not help. **What to do:** Read the job again with GET /v1/jobs/{id} instead of resubmitting it. ## no\_response The run asked a question that was not answered in time, so it stopped. * HTTP status: `409` * Retry: Only as a fresh request with a new retry key. **What to do:** If possible\_commit is true, check the website before running it again; otherwise run it again with a new retry key. | `details` field | Meaning | | - | - | | `possible_commit` | Whether a step may already have changed the website. | ## worker\_lost The run's worker was lost before it finished, and nothing reached the website or the run only reads. * HTTP status: `503` * Retry: Yes. Repeat the same request, with its retry key, after a short wait. **What to do:** Run it again with the same retry key. ## outcome\_unknown The run did not produce a validated result, and it may have changed the website. * HTTP status: `409` * Retry: No. Repeating the request does not help. **What to do:** Check the job and the website before retrying a website action. ## invalid\_output The run's result did not match the tool's output schema. * HTTP status: `409` * Retry: No. Repeating the request does not help. **What to do:** Check the job before retrying a website action; Pomerado repairs the tool. ## execution\_failed The run did not produce a validated result. * HTTP status: `409` * Retry: No. Repeating the request does not help. **What to do:** Check the job before retrying a website action. ## mcp\_not\_hosted This integration has no hosted MCP yet. * HTTP status: `409` * Retry: No. Repeating the request does not help. **What to do:** Try again once the integration's MCP is ready, or use its tools through Pomerado. ## permission\_not\_held A key may carry only permissions you hold now, and an integration key only tools:read, runs:create, jobs:read and jobs:cancel. * HTTP status: `403` * Retry: After changing the request. **What to do:** Ask for fewer permissions, or have an owner or admin grant you the missing ones first. ## api\_key\_limit\_reached This account has as many API keys as it may hold. * HTTP status: `409` * Retry: No. Repeating the request does not help. **What to do:** Revoke a key you no longer use with DELETE /v1/api-keys/{id}, then create another. ## webhook\_limit\_reached This account has as many webhooks as it may hold. * HTTP status: `409` * Retry: No. Repeating the request does not help. **What to do:** Delete a webhook you no longer use with DELETE /v1/webhooks/{id}, then create another. ## webhook\_secret\_unreadable This webhook's signing secret can no longer be read, so nothing can be signed with it. * HTTP status: `409` * Retry: No. Repeating the request does not help. **What to do:** Rotate its secret with POST /v1/webhooks/{id}/rotate-secret, then try again. ## webhooks\_unavailable Webhooks are not available in this Pomerado environment yet. * HTTP status: `403` * Retry: No. Repeating the request does not help. **What to do:** Follow jobs with GET /v1/jobs/{id} instead. ## temporarily\_unavailable A Pomerado service this request needs did not answer, so nothing was done. * HTTP status: `503` * Retry: Yes. Repeat the same request, with its retry key, after a short wait. **What to do:** Wait a few seconds and send the same request again. ## acceptance\_unknown Pomerado could not confirm whether this request was accepted. * HTTP status: `503` * Retry: Yes. Repeat the same request, with its retry key, after a short wait. * A write may already have been accepted; repeat it only with its retry key. **What to do:** Check before repeating it: read a run's or build's job with GET /v1/jobs/{id}, or a saved login's change with GET /v1/connections. A run or build may be sent again with the same retry key; a read is always safe to repeat. ## not\_configured This Pomerado environment does not offer this feature. * HTTP status: `501` * Retry: No. Repeating the request does not help. **What to do:** Use an environment where it is enabled. | `details` field | Meaning | | - | - | | `feature` | The missing feature: `logins`, `sms_numbers` or `billing`. | ## internal\_error Pomerado failed unexpectedly while handling this request. * HTTP status: `500` * Retry: No. Repeating the request does not help. **What to do:** Check whether the request took effect before repeating it; the failure is recorded. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.