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

# Errors

> Error format and codes returned by the GetQR API.

> [!NOTE]
>
> The GetQR API is in beta and is available to selected workspaces. Details may change before the general release.

The GetQR API uses standard HTTP status codes. Successful requests return `2xx`. Failed requests return `4xx` or `5xx` with a JSON body that explains what went wrong.

## Error format

Every error has the same shape: a stable code, a human-readable message and a link to that code's description.

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized: Invalid API key.",
    "doc_url": "https://getqr.com/account/api-docs#error-unauthorized"
  }
}
```

**error.code** `string` *required*

Stable, machine-readable error code. Use it in your code instead of the message. See [Error codes](#error-codes).

**error.message** `string` *required*

Human-readable description of the problem. The wording can change.

**error.doc\_url** `string` *required*

Link to the description of the error code in the API documentation in your GetQR account.

## Error codes

| Code | HTTP status | When it happens |
| - | - | - |
| `bad_request` | 400 | The request is malformed: the body isn't valid JSON, the `Authorization` header lacks the `Bearer ` prefix, or the action isn't allowed in the resource's current state (for example, cancelling a finished bulk creation). |
| `unauthorized` | 401 | The API key is missing or invalid, for example because it was regenerated. |
| `forbidden` | 403 | The workspace owner's subscription isn't active, or your role in the workspace doesn't allow this action. |
| `exceeded_limit` | 403 | You reached a plan limit. On the Single QR plan, creating or duplicating a QR code when the workspace already has one, or starting a bulk creation. |
| `not_found` | 404 | The resource doesn't exist or isn't in your workspace, the endpoint doesn't exist, or the API isn't enabled for your workspace. |
| `method_not_allowed` | 405 | The endpoint exists but doesn't accept this HTTP method. The `Allow` header lists the methods it accepts. |
| `conflict` | 409 | The request clashes with existing data: the short link slug is taken, a request with the same `Idempotency-Key` is still in progress, a schedule overlaps an existing one, or a bulk archive isn't ready yet. |
| `invite_pending` | 409 | You were invited to the workspace but haven't joined yet. API key requests don't return it: the key's workspace is always one you belong to. |
| `invite_expired` | 410 | Your invite to the workspace has expired. API key requests don't return it, for the same reason. |
| `unprocessable_entity` | 422 | The body or query parameters failed validation. The message names the field and what's wrong with it. See [Validation errors](#validation-errors). |
| `rate_limit_exceeded` | 429 | The API key has used up its requests for the current window. See [Rate limits](https://docs.getqr.com/api/rate-limits.md). |
| `internal_server_error` | 500 | Something went wrong on our side. Retry later, and contact support if it keeps happening. |

## Validation errors

When the body or query parameters fail validation, the API answers `422`. The message describes the first invalid field as `<issue>: <field>: <details>`:

```json theme={null}
{
  "error": {
    "code": "unprocessable_entity",
    "message": "too_big: pageSize: Max page size is 100.",
    "doc_url": "https://getqr.com/account/api-docs#error-unprocessable_entity"
  }
}
```

Nested fields use dot notation, for example `link.url`.

## Handle errors

* Branch on `error.code`, not on `error.message`.
* Don't retry `4xx` errors unchanged: fix the request first. The exceptions are a `409` for a request still in progress and `429`.
* On `429`, wait for the number of seconds in the `Retry-After` header. See [Rate limits](https://docs.getqr.com/api/rate-limits.md#when-you-go-over-the-limit).
* Retry `5xx` errors with exponential backoff.

## Common issues

> [accordion] Every request returns 404 "This endpoint is not available."
>
> The API is in beta and isn't enabled for your workspace yet.

> [accordion] 404 "This endpoint does not exist."
>
> The path is wrong. Check it against the endpoint pages, and that it starts with `/api/v1/`.

> [accordion] 403 "Access denied: This account does not have an active subscription."
>
> The workspace owner's subscription has ended. The API key works again as soon as the owner resubscribes.

> [accordion] 403 "API access is not available for this role."
>
> Your role in the workspace is viewer. Only the workspace owner and editors can use the API.

## What's next

> [card] [Rate limits](https://docs.getqr.com/api/rate-limits.md)

> [card] [Authentication](https://docs.getqr.com/api/authentication.md)


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