---
title: "API errors"
description: "Read Cool Computers HTTP failures as application/problem+json and act on their stable codes."
canonical: "https://www.cool.computer/docs/api-reference/errors"
last_updated: "2026-11-20"
---
# API errors

> Read Cool Computers HTTP failures as application/problem+json and act on their stable codes.

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

```json
{
  "type": "https://cool.computer/docs/api-reference/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.
