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

# Error handling

> Error response format, common error codes, and retry strategy

Every error uses the same format. Branch on `code` and use `message` only for human readers.

```json theme={null}
{
  "code": "PROMPT_SET_NOT_FOUND",
  "message": "프롬프트 세트를 찾을 수 없습니다"
}
```

Validation errors include a `details` array listing each field violation.

```json theme={null}
{
  "code": "COMMON_VALIDATION",
  "message": "데이터 검증에 실패했습니다",
  "details": [
    "models: 최소 1개 이상이어야 합니다",
    "keywords: 최대 100개까지 입력할 수 있습니다"
  ]
}
```

> [!NOTE]
>
> Error messages are returned in Korean (`ko`) or English (`en`) based on the
> `Accept-Language` header. If the header is missing or the language is not
> supported, messages are returned in English. The `code` value is always the
> same regardless of language.

## HTTP status codes

| Status | Meaning | What to do |
| - | - | - |
| `400` | Bad request (validation failure, invalid cursor, etc.) | Fix the request and retry. Retrying the same request has no effect |
| `401` | Authentication failed | Check the `API-Key` header and the key value |
| `402` | Insufficient credits (`INSUFFICIENT_CREDITS`) | Check your balance with `GET /credits/me` and top up. See [Credits](https://docs.trychainshift.ai/en/guides/credits.md) |
| `404` | Resource not found | Check that the ID belongs to a resource in your organization |
| `409` | State conflict (for example, more than 1,000 prompts per set) | Check the resource state and adjust the request |
| `413` | Request body exceeds 2MiB (`COMMON_REQUEST_BODY_TOO_LARGE`) | Split the request into smaller parts |
| `429` | Rate limit exceeded | Wait for the seconds in the `Retry-After` header and retry. See [Rate limit](https://docs.trychainshift.ai/en/guides/rate-limit.md) |
| `5xx` | Server error or external provider outage | Retry with exponential backoff |

## Common error codes

These codes can occur on any endpoint. Write the handling logic for them once and reuse it across all calls.

| Code | HTTP | Description |
| - | - | - |
| `COMMON_BINDING` | 400 | The request body could not be parsed (malformed JSON, etc.) |
| `COMMON_VALIDATION` | 400 | Field validation failed. `details` lists the violations |
| `COMMON_INVALID_CURSOR` | 400 | Invalid cursor format. Start again from the first page |
| `PLATFORM_INVALID_ID` | 400 | Invalid resource ID format. This is a format problem, not a missing resource, so it is `400` rather than `404` |
| `COMMON_UNAUTHORIZED` | 401 | Authentication failed |
| `INSUFFICIENT_CREDITS` | 402 | Insufficient credits |
| `COMMON_REQUEST_BODY_TOO_LARGE` | 413 | Request body exceeds 2MiB |
| `PLATFORM_RATE_LIMIT_EXCEEDED` | 429 | Rate limit exceeded |

## Endpoint-specific errors

Codes that only occur on a specific resource, such as `PROMPT_SET_NOT_FOUND` or `RUN_TOO_MANY_TASKS`, are not covered here. The **Errors** table at the top of each [API Reference](https://docs.trychainshift.ai/en/api-reference/overview.md) page lists only the codes that endpoint actually returns. The table is generated from the API spec, so it always matches the server.

> [!NOTE]
>
> The code prefix identifies the resource. Prompts use `QUESTION_`, brands use
> `USER_BRAND_`, prompt sets use `PROMPT_SET_`, and run requests use `RUN_`.

## Retry strategy

* `429`: wait for the number of seconds in the `Retry-After` header, then retry.
* `502` / `503`: this may be an external provider outage. Retry with exponential backoff (for example, 1s, then 2s, then 4s).
* `400` / `404`: retrying returns the same result. Fix the request instead.
* If a transient error occurs while polling, collection for the run continues in the background. Pick up where you left off on the next poll.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.