> ## Documentation Index
> Fetch the complete documentation index at: https://docs.duckie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Responses

> Handle API errors consistently

Duckie API errors use a single JSON shape.

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "limit must be a positive integer",
    "request_id": "req_123"
  }
}
```

Always log `request_id` when you contact Duckie support about a failed API request.

## Error Codes

| HTTP status | Code                | Meaning                                                                        |
| ----------- | ------------------- | ------------------------------------------------------------------------------ |
| `400`       | `invalid_request`   | A path parameter, query parameter, cursor, or request format was invalid       |
| `401`       | `unauthenticated`   | The `Authorization` header is missing, malformed, unknown, expired, or revoked |
| `403`       | `permission_denied` | The API key does not include the required read scope                           |
| `404`       | `not_found`         | The requested resource was not found in the API key's organization             |
| `429`       | `rate_limited`      | A pre-auth, key, organization, or endpoint rate limit was exceeded             |
| `500`       | `internal_error`    | Duckie could not complete the request                                          |

## Authentication Errors

Missing or malformed authentication returns:

```json theme={null}
{
  "error": {
    "code": "unauthenticated",
    "message": "Authorization header must be 'Bearer <api_key>'",
    "request_id": "req_123"
  }
}
```

Unknown, expired, or revoked keys return:

```json theme={null}
{
  "error": {
    "code": "unauthenticated",
    "message": "Invalid API key",
    "request_id": "req_123"
  }
}
```

## Permission Errors

If a key is valid but lacks the required scope, the API returns:

```json theme={null}
{
  "error": {
    "code": "permission_denied",
    "message": "API key does not have the required scope",
    "request_id": "req_123"
  }
}
```

Create a new key with the needed scope or update your integration to call only endpoints the key can access.

## Not Found Errors

Detail endpoints return `404 not_found` when the resource does not exist in the API key's organization. This includes valid UUIDs that belong to another organization.