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

# Errors

> Error response format and error codes reference

## Error format

All errors follow a consistent JSON structure:

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "QR code not found",
    "doc_url": "https://docs.useqrkit.com/errors#not_found",
    "request_id": "req_abc123"
  }
}
```

| Field        | Description                                                    |
| ------------ | -------------------------------------------------------------- |
| `code`       | Machine-readable error code                                    |
| `message`    | Human-readable description                                     |
| `doc_url`    | Link to relevant documentation                                 |
| `request_id` | Unique ID for debugging (include this when contacting support) |

## Error codes

| HTTP Status | Code                   | Description                                                             |
| ----------- | ---------------------- | ----------------------------------------------------------------------- |
| `400`       | `invalid_request`      | The request body is malformed or missing required fields                |
| `401`       | `unauthorized`         | Missing or invalid API key                                              |
| `403`       | `forbidden`            | The API key does not have the required scope                            |
| `404`       | `not_found`            | The requested resource does not exist                                   |
| `409`       | `conflict`             | A resource with that identifier already exists                          |
| `422`       | `unprocessable_entity` | The request is valid but cannot be processed (e.g., plan limit reached) |
| `429`       | `rate_limit_exceeded`  | Too many requests — see [Rate Limiting](/rate-limiting)                 |
| `500`       | `internal_error`       | An unexpected error occurred on our end                                 |

## Example responses

### 400 — Invalid request

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "target.type must be one of: url, text, email, sms, wifi, event, vcard",
    "doc_url": "https://docs.useqrkit.com/errors#invalid_request",
    "request_id": "req_x1y2z3"
  }
}
```

### 401 — Unauthorized

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key",
    "doc_url": "https://docs.useqrkit.com/errors#unauthorized",
    "request_id": "req_a1b2c3"
  }
}
```

### 404 — Not found

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "QR code 'qr_999' not found",
    "doc_url": "https://docs.useqrkit.com/errors#not_found",
    "request_id": "req_d4e5f6"
  }
}
```

### 422 — Plan limit reached

```json theme={null}
{
  "error": {
    "code": "unprocessable_entity",
    "message": "QR code limit reached for your plan. Upgrade to create more.",
    "doc_url": "https://docs.useqrkit.com/errors#unprocessable_entity",
    "request_id": "req_g7h8i9"
  }
}
```

### 429 — Rate limited

```json theme={null}
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 30 seconds.",
    "doc_url": "https://docs.useqrkit.com/errors#rate_limit_exceeded",
    "request_id": "req_j1k2l3"
  }
}
```

## Handling errors

<CodeGroup>
  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.useqrkit.com/v1/qr-codes",
      headers={"Authorization": "Bearer qr_live_..."},
      json={"target": {"type": "url", "destination": "https://example.com"}},
  )

  if not response.ok:
      error = response.json()["error"]
      print(f"Error {response.status_code}: {error['code']} — {error['message']}")
      print(f"Request ID: {error['request_id']}")
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.useqrkit.com/v1/qr-codes", {
    method: "POST",
    headers: {
      Authorization: "Bearer qr_live_...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      target: { type: "url", destination: "https://example.com" },
    }),
  });

  if (!response.ok) {
    const { error } = await response.json();
    console.error(`Error ${response.status}: ${error.code} — ${error.message}`);
    console.error(`Request ID: ${error.request_id}`);
  }
  ```
</CodeGroup>