Skip to main content
All errors use one envelope: 
{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "status filter other than open is not supported for type=poll",
    "details": { "field": "status" }
  }
}
code is the stable contract — branch on it, not on message wording. details is optional context (offending field, retry_after seconds, …).

​
Error codes

codeHTTPWhen
UNAUTHORIZED401Missing, invalid, revoked, or expired key; or the key’s account is no longer active
FORBIDDEN403Reserved for future scopes (not currently returned)
NOT_FOUND404Resource doesn’t exist, unknown handle, hidden by privacy settings, or removed by moderation — existence is never leaked
INVALID_ARGUMENT400Parameter validation failed (details.field names it)
RATE_LIMITED429Over quota — see Rate limits
SERVICE_DISABLED503The Open API is temporarily switched off (maintenance/emergency)
INTERNAL500Our bug — retry once, then back off

​
Real examples

401 — no key (captured live): 
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Provide an API key: Authorization: Bearer sspat_…"
  }
}
401 responses carry a WWW-Authenticate: Bearer realm="seesaw-open-api" header. Depending on the network path it may arrive under the name x-amzn-remapped-www-authenticate — match either when debugging.
400 — invalid argument (captured live): 
{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "status filter other than open is not supported for type=poll",
    "details": { "field": "status" }
  }
}
429 — rate limited: see Rate limits for the full shape and headers.

​
404 semantics worth knowing

A 404 does not distinguish between “never existed”, “hidden by the owner’s privacy settings”, and “removed by moderation” — deliberately. Don’t retry 404s; surface them as “not available”. Over MCP, errors arrive as tool errors with the same message text (e.g. resource not found), so agents get the same signal.