API errors - Genseo

Genseo returns stable error codes so API clients, CLIs, and agents can respond predictably.

Error response shape

{
  "error": {
    "code": "project_forbidden",
    "message": "This API key cannot access the requested project."
  }
}

Codes

Code	Meaning	Retry behavior
`invalid_api_key`	Missing, malformed, or unknown project API key	Do not retry without a new key
`invalid_oauth_token`	The token is not a verified Genseo MCP token, has the wrong audience, or expired	Reauthorize or refresh; do not use a browser session token
`key_revoked`	The key was deleted or revoked	Do not retry; create a new key
`key_expired`	The key has expired	Do not retry; create a new key
`insufficient_scope`	The key cannot perform the requested action	Do not retry without changing access
`project_forbidden`	The request targets a different project	Final; do not retry
`project_required`	A project operation omitted `project_id`	Select one accessible project and retry once
`resource_not_found`	The resource is missing or belongs to another project	Do not assume it exists elsewhere
`validation_error`	Request body or parameters are invalid	Fix the request before retrying
`agent_autonomy_required`	An OAuth agent attempted a write while Agent Autonomy is disabled	Ask the user to enable it in the dashboard; do not retry automatically
`action_not_available`	An agent attempted an excluded action such as destructive deletion	Perform the action manually in Genseo if intended
`rate_limit_exceeded`	A credential, workspace, Audit, or Recheck limit was reached	Honor `Retry-After` and retry once after the reset
`rate_limit_unavailable`	Distributed request protection is temporarily unavailable	Retry later; write side effects were not started
`usage_limit_reached`	The project has reached an internal product limit	Wait, upgrade, or ask the user
`audit_already_running`	The project already has an active Audit	Poll the current Audit instead of starting another
`generation_already_running`	A generation job is already active	Wait and read the resource later
`integration_not_configured`	Publishing requires a connected provider	Configure an integration first
`mapping_required`	Provider field mapping is missing	Save mapping before retrying

Agent recommendations

Show the stable code to the user when an action fails.
Treat authorization and project-boundary errors as final.
Back off on rate limits.
Never work around a project boundary by trying another ID.
For generation conflicts, wait before checking the post or keyword state again.

Rate-limit responses

Rate limits are reserved before crawls, AI providers, publishing, or other chargeable side effects begin. A rejected request therefore does not start that work.

HTTP/1.1 429 Too Many Requests
Retry-After: 37
RateLimit-Limit: 30
RateLimit-Remaining: 0
RateLimit-Reset: 1788892860
Content-Type: application/json

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after the indicated delay.",
    "details": {
      "retryAfter": 37,
      "resetAt": "2026-09-08T18:41:00.000Z"
    }
  }
}

MCP returns the same error details in its JSON fallback so an agent can pause for retryAfter seconds. Add small random jitter, retry only after the stated time, and stop after repeated failures.