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

# Errors

> HTTP status, error body, and optional details

All error bodies are JSON (messages in English). **`error.code` is an integer and always matches the HTTP status** of the response.

## Shape

```json theme={null}
{
  "error": {
    "code": 400,
    "message": "Field \"name\" is required",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "details": {
      "field": "name",
      "reason": "required_field"
    }
  }
}
```

* **`request_id`** — correlate with the **`X-Request-Id`** response header.
* **`details`** — optional object; extra keys allowed for forward compatibility.

## HTTP status reference

| HTTP    | Typical case                                                                         |
| ------- | ------------------------------------------------------------------------------------ |
| **400** | Validation (bad JSON, missing field, duplicate name on create tag / project code, …) |
| **401** | Missing API key, invalid key, or revoked key                                         |
| **403** | Forbidden (action or resource not allowed for this key / team)                       |
| **404** | Resource not found (e.g. activity report not visible for this team)                  |
| **429** | Rate limited (`details.retryAfterSeconds`; see [Rate limits](/rate-limits))          |
| **500** | Unexpected server error                                                              |

Distinguish multiple **401** or **400** cases using **`message`** and **`details`**.

## Validation `details.reason` (create tag / project code)

When `code` is **400** from those endpoints, `details.reason` may be:

* `invalid_json` — body is not valid JSON
* `required_field` — e.g. missing `name` (`details.field` may be `name`)
* `duplicate_name` — name already exists for the team (`details.field` may be `name`)

Full JSON schemas: OpenAPI components **PublicError**, **PublicErrorDetails**, **PartnerValidationErrorReason** (see **API Reference** in this site, sourced from `openapi.yaml`).