API errors

Ordinary HTTP API failures use application/problem+json. Read the status and stable code before deciding what to do.

{
  "type": "https://www.cool.computer/docs#api-errors",
  "title": "Unauthorized",
  "status": 401,
  "code": "authentication_required",
  "detail": "unauthorized",
  "resolution": "Authenticate with a bearer credential and retry."
}

Fields

code is the machine-readable reason.
detail explains this failure.
resolution tells a caller what can correct it.
status repeats the HTTP status when a response includes it.

Common responses

Status	What to do
`400`	Correct the request body, parameter, email address, or code format.
`401`	Authenticate again or replace the expired credential.
`403`	Use the required credential type or ask the owner for approval.
`404`	Check the route and resource identifier.
`409`	Refresh the resource state before deciding whether to retry.
`429`	Stop and wait. Do not loop on an email-code request.
`503`	Retry later without changing authentication methods.

interactive_required means a person must finish the named action. Give the owner the supplied URL or instruction and wait for them. access_token_required means the bearer credential is the wrong type for the operation. Use an owner access token from email sign-in to create, list, or revoke keys. A claimed WorkOS agent access token can create a key, but cannot list or revoke keys. An API key cannot manage keys through /api/api-keys. Signed-in owners can also manage keys in Settings using their browser session.

Authentication challenges

A protected HTTP endpoint can return WWW-Authenticate: Bearer with resource_metadata for the requested resource. The API metadata explains bearer-header use. It does not make an MCP token valid for the HTTP API.

Start here

Connect your agent

Your computer

Use it

Build with the API

Endpoint reference

Fields

Common responses

Authentication challenges