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

# API errors and HTTP status codes

> Every HTTP error code, JSON response shape, rate limit header and guidance on handling each error.

The Tikk API uses standard HTTP status codes to signal success and failure. Every error response includes a JSON body with at least a `message` field describing what went wrong. Build your error handling around the HTTP status code first, then read `message` for additional context.

## Error codes

| Status                     | When it occurs                                                                 |
| -------------------------- | ------------------------------------------------------------------------------ |
| `401 Unauthorized`         | No credential was sent, or the credential is revoked, expired, or unrecognized |
| `403 Forbidden`            | The credential is valid but lacks the required scope for this endpoint         |
| `404 Not Found`            | The requested resource does not exist on your account                          |
| `422 Unprocessable Entity` | One or more query parameters failed validation                                 |
| `429 Too Many Requests`    | You have sent more than 60 requests in a 60-second window                      |

## Standard error body

All errors except `422` return a JSON body with a single `message` field:

```json theme={null}
{
  "message": "Unauthenticated."
}
```

Check the `message` value for a human-readable description. Don't rely on the exact wording in code. Key your error handling on the HTTP status code.

## Validation error body (422)

When a request fails validation, the response body includes an `errors` object keyed by the name of each invalid parameter. Each key maps to an array of one or more error strings describing the problem with that parameter:

```json theme={null}
{
  "message": "The to field must be a date after or equal to from.",
  "errors": {
    "to": [
      "The to field must be a date after or equal to from."
    ]
  }
}
```

Iterate over the `errors` object to surface specific field-level messages to your users or logs.

## Rate limiting (429)

Tikk allows 60 requests per minute per credential. When you exceed this limit, the API responds with `429 Too Many Requests` and includes a `Retry-After` header indicating the number of seconds to wait before retrying:

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 42
```

Read the `Retry-After` header and pause your requests for at least that many seconds before retrying. The following example shows how to handle a `429` response and respect the header:

```javascript theme={null}
async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status !== 429) {
      return response;
    }

    const retryAfter = parseInt(response.headers.get("Retry-After") ?? "60", 10);
    console.warn(`Rate limited. Retrying in ${retryAfter}s...`);
    await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
  }

  throw new Error("Max retries reached after repeated 429 responses.");
}
```

<Tip>
  In production integrations, combine the `Retry-After` header with exponential backoff and jitter so that multiple instances of your service do not all retry simultaneously after a rate-limit window resets. A simple rule: always wait at least as long as `Retry-After` specifies, then add a random delay before the next attempt.
</Tip>

## 404 and user isolation

The API enforces strict user isolation. A booking ID or service slug that exists but belongs to another user returns `404 Not Found`, not `403 Forbidden`. The API never confirms whether a resource exists outside your account. On a `404`, check the ID or slug belongs to a resource on your account before assuming it doesn't exist.