> ## 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.

# Erros

> Formato e códigos de erro retornados pela API do GetQR.

> [!NOTE]
>
> A API do GetQR está em beta e disponível para workspaces selecionados. Os detalhes podem mudar antes do lançamento oficial.

A API do GetQR usa os códigos de status HTTP padrão. Requisições bem-sucedidas retornam `2xx`. Requisições com falha retornam `4xx` ou `5xx` com um corpo JSON que explica o que deu errado.

## Formato do erro

Todo erro tem o mesmo formato: um código estável, uma mensagem legível e um link para a descrição desse código.

```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*

Código de erro estável e legível por máquina. Use-o no seu código em vez da mensagem. Veja [Códigos de erro](#códigos-de-erro).

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

Descrição legível do problema. O texto pode mudar.

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

Link para a descrição do código de erro na documentação da API da sua conta GetQR.

## Códigos de erro

| Código | Status HTTP | Quando acontece |
| - | - | - |
| `bad_request` | 400 | A requisição está malformada: o corpo não é um JSON válido, o cabeçalho `Authorization` está sem o prefixo `Bearer ` ou a ação não é permitida no estado atual do recurso (por exemplo, cancelar uma criação em massa já concluída). |
| `unauthorized` | 401 | A chave de API está ausente ou é inválida, por exemplo porque foi regenerada. |
| `forbidden` | 403 | A assinatura do proprietário do workspace não está ativa, ou sua função no workspace não permite esta ação. |
| `exceeded_limit` | 403 | Você atingiu um limite do plano. No plano Single QR: criar ou duplicar um QR code quando o workspace já tem um, ou iniciar uma criação em massa. |
| `not_found` | 404 | O recurso não existe ou não pertence ao seu workspace, o endpoint não existe ou a API não está habilitada para o seu workspace. |
| `method_not_allowed` | 405 | O endpoint existe, mas não aceita este método HTTP. O cabeçalho `Allow` lista os métodos que ele aceita. |
| `conflict` | 409 | A requisição conflita com dados existentes: o slug do link curto já está em uso, uma requisição com a mesma `Idempotency-Key` ainda está em andamento, um agendamento se sobrepõe a outro existente ou um arquivo ZIP em massa ainda não está pronto. |
| `invite_pending` | 409 | Você foi convidado para o workspace, mas ainda não entrou. Requisições com chave de API não o retornam: o workspace da chave é sempre um do qual você faz parte. |
| `invite_expired` | 410 | Seu convite para o workspace expirou. Requisições com chave de API não o retornam, pelo mesmo motivo. |
| `unprocessable_entity` | 422 | O corpo ou os parâmetros de consulta não passaram na validação. A mensagem indica o campo e o problema. Veja [Erros de validação](#erros-de-validação). |
| `rate_limit_exceeded` | 429 | A chave de API esgotou as requisições da janela atual. Veja [Limites de requisições](https://docs.getqr.com/pt-br/api/rate-limits.md). |
| `internal_server_error` | 500 | Algo deu errado do nosso lado. Tente de novo mais tarde e fale com o suporte se continuar acontecendo. |

## Erros de validação

Quando o corpo ou os parâmetros de consulta não passam na validação, a API responde `422`. A mensagem descreve o primeiro campo inválido no formato `<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"
  }
}
```

Campos aninhados usam notação de ponto, por exemplo `link.url`.

## Como tratar erros

* Decida com base em `error.code`, não em `error.message`.
* Não repita erros `4xx` sem mudanças: corrija a requisição primeiro. As exceções são um `409` de uma requisição ainda em andamento e o `429`.
* Em caso de `429`, aguarde o número de segundos do cabeçalho `Retry-After`. Veja [Limites de requisições](https://docs.getqr.com/pt-br/api/rate-limits.md#quando-você-ultrapassa-o-limite).
* Repita erros `5xx` com backoff exponencial.

## Problemas comuns

> [accordion] Toda requisição retorna 404 "This endpoint is not available."
>
> A API está em beta e ainda não está habilitada para o seu workspace.

> [accordion] 404 "This endpoint does not exist."
>
> O caminho está errado. Compare-o com as páginas dos endpoints e verifique se ele começa com `/api/v1/`.

> [accordion] 403 "Access denied: This account does not have an active subscription."
>
> A assinatura do proprietário do workspace terminou. A chave de API volta a funcionar assim que o proprietário assinar de novo.

> [accordion] 403 "API access is not available for this role."
>
> Sua função no workspace é Viewer. Somente o proprietário do workspace e os Editors podem usar a API.

## Próximos passos

> [card] [Limites de requisições](https://docs.getqr.com/pt-br/api/rate-limits.md)

> [card] [Autenticação](https://docs.getqr.com/pt-br/api/authentication.md)


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