Errors

Every non-2xx Service API response uses the same envelope:

{
  "error": {
    "code": "not_found",
    "message": "Not found.",
    "requestId": "3f0c1a52-7d0e-4b8e-9a51-2c7f6d1e9b44"
  }
}

• code is always one of the codes in the table below — build your error handling on code, not on message.
• requestId is a unique id for this request. If an error persists, quote it to support; it identifies exactly what happened on our side.
• details is present on some 4xx errors and carries structured, code-specific information that helps you fix the request (see below). Server-side errors (5xx) never carry details and always use a generic message.
• A resource that belongs to another project or organization returns the same 404 not_found as a resource that doesn’t exist, so a key can never learn whether someone else’s resource exists.

When request parameters or the body fail validation, details.issues lists what to fix:

{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed",
    "requestId": "…",
    "details": { "issues": [{ "in": "params", "path": "/id", "message": "Invalid cuid" }] }
  }
}

in is body, params, or querystring; path is a JSON pointer into that part of the request.

Error codes

Code	HTTP	When
unauthorized	401	Missing, invalid, or revoked API key.
forbidden	403	The key itself isn’t allowed here — a publishable key, or a key whose scope can’t call this endpoint.
not_found	404	The resource doesn’t exist or belongs to a different project or organization — including when a body field (not just the URL) names another project’s resource. Also returned for an unknown path.
invalid_request	400	The request body or parameters failed validation, or the body isn’t valid JSON.
payload_too_large	413	The request body, or a flow configuration inside it (limit 256 KiB), is too large.
secret_keys_not_mintable	400	POST /v1/projects/{projectId}/keys was called with keyType: "secret" — only publishable keys can be minted this way.
not_yet_supported	501	Reading or writing the design of a simple-kind Conversation — not yet available through this API.
unsupported_step	501	The stored design uses a step kind this API doesn’t yet expose. Edit the conversation in the dashboard instead.
invalid_transition	422	A Conversation Design write names a target step id that isn’t in the document.
invalid_route_option	422	A route step option has only one of title/description, or neither that pair nor a target.
invalid_layout_ref	422	A layout entry names a step id that isn’t in the document.
unknown_integration_ref	422	A design write references an integration id the project doesn’t have.
integration_kind_mismatch	422	A design’s integration reference kind doesn’t match the integration’s actual kind.
design_invalid	422	The saved design was rejected by server-side validation. details.issues is an array of { stepId, message }.
flow_schema_invalid	422	A simple flow configuration was rejected — an unknown field, a wrong type, or a value that doesn’t match the published flow format. details.issues is an array of { path, message }.
ai_disclosure_required	422	A changed greeting or recording-consent line doesn’t clearly disclose that the caller is speaking with an AI.
simple_agent_invalid	422	A Simple-project agent update was rejected (for example a locked skill or an invalid skill setting).
plan_limit_exceeded	422 (saving a design) / 403 (elsewhere)	Over a plan limit (conversation size, number of conversations/knowledge bases/phone numbers). details includes the limit, current usage, and plan.
cannot_revoke_current_key	409	POST /v1/keys/{id}/revoke was called with the same key that’s authenticating the request.
usage_unavailable	501 / 503	501: usage reporting is not available on this API yet. 503: live usage data is temporarily unavailable — retry.
validation_unavailable	503	Validation is temporarily unreachable — nothing was written; retry.
agent_config_unavailable	503	Simple-project agent configuration is temporarily unavailable — nothing was written; retry.
kb_query_unavailable	503	Knowledge base search is temporarily unavailable — retry.
internal_error	500 / 502	An unexpected failure on our side. Safe to retry after a short delay; if it persists, report it with the requestId.

Also see

• Resources
• Conversation Design