Errors - Pomerado

Every error from the REST API, the Dashboard and MCP tools has the same shape:

{
  "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//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//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/, 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/.

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/, 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/, 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/, 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/ 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/.

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/ 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//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//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/ 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/, 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/, 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//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/ 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/, 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.

​invalid_request

​invalid_answer

​invalid_input

​input_rejected

​unsupported_login_field

​effect_required

​invalid_email

​request_too_large

​method_not_allowed

​not_found

​unauthorized

​session_refresh_required

​reauthentication_required

​forbidden

​stale_grant

​save_forbidden

​account_unsupported

​organization_access_removed

​account_deletion_pending

​sign_in_required

​try_limit_reached

​try_tier_unavailable

​sign_in_limit_reached

​sign_in_unavailable

​access_denied

​expired_token

​account_selection_required

​saved_login_conflict

​login_identity_conflict

​site_login_exists

​legacy_duplicate_saved_logins

​saved_login_unsettled

​login_in_use

​login_save_in_progress

​invalid_credential

​authenticator_not_configured

​credentials_rejected

​pin_required

​pin_not_set

​pin_already_set

​invalid_pin

​pin_mismatch

​wrong_pin

​pin_throttled

​sms_number_not_allowed

​sms_number_not_linked

​sms_number_cap_reached

​sms_number_purchase_failed

​site_not_supported

​quota_exceeded

​quota_expired

​website_pending

​retry_conflict

​execution_budget_exhausted

​input_expired

​input_not_pending

​input_declined

​input_cancelled

​result_expired

​result_unavailable

​no_response

​worker_lost

​outcome_unknown

​invalid_output

​execution_failed

​mcp_not_hosted

​permission_not_held

​api_key_limit_reached

​webhook_limit_reached

​webhook_secret_unreadable

​webhooks_unavailable

​temporarily_unavailable

​acceptance_unknown

​not_configured

​internal_error