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

# Error Handling

> API errors, status codes, and response shape

Errors from the InkLink API use a shared JSON shape.

All of them expect the **`api-key`** header (see [Authentication](/authentication)).

## HTTP status codes

| Status  | Typical meaning                             | What to do                                                 |
| ------- | ------------------------------------------- | ---------------------------------------------------------- |
| **200** | Success                                     | Parse the JSON body                                        |
| **400** | Validation failed (`VALIDATION_ERROR`)      | Fix the request using `error.details`                      |
| **401** | Not authenticated (`UNAUTHORIZED`)          | Send a valid **`api-key`**                                 |
| **404** | Resource missing (`NOT_FOUND`)              | Check **`id`** belongs to your org and exists              |
| **429** | Rate or usage limit (`RATE_LIMIT_EXCEEDED`) | Retry with backoff; check quotas                           |
| **500** | Server error (`INTERNAL_ERROR`)             | Retry with backoff; If the issue persists, contact support |

## Error response format

```json theme={"dark"}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "One or more fields failed validation.",
    "details": [
      { "field": "subject_id", "message": "String must contain at least 1 character(s)" }
    ],
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

* **`code`** - Machine-readable enum (see below).
* **`message`** - Short description for logging or UI.
* **`details`** - Array of `{ "field", "message" }`. Root-level validation messages may use an empty **`field`** (`""`).
* **`requestId`** - Correlates with the **`x-request-id`** response header; use it with support.

## Error `code` values

| `code`                | HTTP | Description                                                                                                        |
| --------------------- | ---- | ------------------------------------------------------------------------------------------------------------------ |
| `VALIDATION_ERROR`    | 400  | Body or path input failed validation (see **`details`**)                                                           |
| `UNAUTHORIZED`        | 401  | Invalid or missing **`api-key`** (or no session, for dashboard-internal calls)                                     |
| `NOT_FOUND`           | 404  | Inquiry or result not found for your organization (e.g. wrong **`id`** or not visible to your org)                 |
| `RATE_LIMIT_EXCEEDED` | 429  | API key verification or org usage hit a rate or quota limit (**`message`** may include provider text)              |
| `INTERNAL_ERROR`      | 500  | Unexpected failure or guarded server error (**`message`** may vary); unhandled exceptions return a generic message |