Errors
One error shape, stable codes, a fix for each.
Every error uses the same shape. doc_url links straight to the matching entry below, and request_id is what to send support.
{
"error": {
"code": "rate_limit_exceeded",
"message": "…",
"request_id": "req_…",
"doc_url": "https://messyapi.com/docs/errors#rate_limit_exceeded"
}
}invalid_request HTTP 400 · fix the request
The request was rejected before any work ran — a field failed validation or an operation wasn't composable.
What to do: Fix the reported field or step, then resend.
invalid_json HTTP 400 · fix the request
The request body could not be parsed as JSON.
What to do: Check the payload is valid JSON and Content-Type is application/json.
payload_too_large HTTP 413 · fix the request
The request exceeded the maximum accepted size for this endpoint.
What to do: Split the records into smaller batches and resend.
invalid_api_key HTTP 401 · fix the request
The API key supplied was not recognized.
What to do: Verify the key in Dashboard → API Keys, then resend.
revoked_api_key HTTP 401 · fix the request
The API key used for this request has been revoked.
What to do: Create a new key in Dashboard → API Keys and update your client.
forbidden HTTP 403 · fix the request
The credentials were valid but not permitted to perform this action or reach this resource.
What to do: Use a key scoped to the correct project or capability.
not_found HTTP 404 · fix the request
The referenced resource does not exist in this workspace.
conflict HTTP 409 · fix the request
The request conflicted with the current state — often an idempotency key reused with a different body.
What to do: Use a fresh idempotency key for a new operation.
blocked_by_policy HTTP 422 · fix the request
Agent Guard found risky content (prompt injection, a secret or personal data) and your agent_policy=block refused it.
What to do: Remove the flagged values, or use agent_policy=redact to mask them.
policy_denied HTTP 403 · fix the request
A policy on this account blocked the agent request before anything ran. Nothing was charged.
What to do: Read the policy named in the error, then change the request or ask the account owner to adjust the policy.
approval_required HTTP 202 · fix the request
A policy requires a person to approve this agent request. It is waiting in the account's Approvals queue and nothing was charged.
What to do: After a person approves it, resend the exact same request with the returned approval_id (body field or X-Messy-Approval header). It runs once and is charged only then.
approval_expired HTTP 410 · fix the request
Nobody approved the request before it expired, so it was cancelled and nothing was charged.
What to do: Send the request again if it is still needed.
agent_disabled HTTP 403 · fix the request
Agent access is switched off for this account or key (kill switch). Ordinary API calls are not affected.
What to do: Ask the account owner to turn agent access back on.
unsupported_capability HTTP 422 · fix the request
The AI skill couldn't map the request to any MessyAPI operation, so nothing ran and nothing was charged. MessyAPI never guesses or invents a capability.
What to do: Call messy_discover (GET /api/v1/ai/discover?goal=...) to see what is supported, then rephrase or pass explicit operations.
usage_limit_exceeded HTTP 429 · retryable
This request would exceed your plan's usage allowance for the current period.
What to do: Increase your plan or enable overage in Billing, then retry.
rate_limit_exceeded HTTP 429 · retryable
Requests arrived faster than the endpoint's rate limit permits.
What to do: Back off and retry after the window resets (see the Retry-After header).
internal_error HTTP 500 · retryable
An unexpected error occurred while processing the request.
What to do: Retry with the same idempotency key; if it persists, contact support with this request ID.
Test your error handling
With a test key, send X-Messy-Simulate: <code> to get any of these errors back on purpose. See Test & live modes.
Unknown errors return a sanitized message — never a stack trace.