> ## 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 devolvidos pela API do GetQR.

> [!NOTE]
>
> A API do GetQR está em versão beta e só está disponível para alguns espaços de trabalho. Os detalhes podem mudar antes do lançamento geral.

A API do GetQR usa os códigos de estado HTTP padrão. Os pedidos bem-sucedidos devolvem `2xx`. Os pedidos falhados devolvem `4xx` ou `5xx` com um corpo JSON que explica o que correu mal.

## Formato dos erros

Todos os erros têm a mesma estrutura: um código estável, uma mensagem legível e uma ligação 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. Utilize-o no seu código em vez da mensagem. Consulte [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*

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

## Códigos de erro

| Código | Estado HTTP | Quando acontece |
| - | - | - |
| `bad_request` | 400 | O pedido está mal formado: o corpo não é JSON válido, falta o prefixo `Bearer ` no cabeçalho `Authorization` 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á em falta ou é inválida, por exemplo porque foi regenerada. |
| `forbidden` | 403 | A subscrição do dono do espaço de trabalho não está ativa, ou a sua função no espaço de trabalho não permite esta ação. |
| `exceeded_limit` | 403 | Atingiu um limite do plano. No plano Single QR, ao criar ou duplicar um código QR quando o espaço de trabalho já tem um, ou ao iniciar uma criação em massa. |
| `not_found` | 404 | O recurso não existe ou não pertence ao seu espaço de trabalho, o endpoint não existe, ou a API não está ativada para o seu espaço de trabalho. |
| `method_not_allowed` | 405 | O endpoint existe, mas não aceita este método HTTP. O cabeçalho `Allow` indica os métodos que aceita. |
| `conflict` | 409 | O pedido entra em conflito com dados existentes: o slug da ligação curta já está a ser utilizado, um pedido com a mesma `Idempotency-Key` ainda está em curso, um agendamento sobrepõe-se a outro existente ou um arquivo da criação em massa ainda não está pronto. |
| `invite_pending` | 409 | Foi convidado para o espaço de trabalho, mas ainda não aderiu. Os pedidos com chave de API não o devolvem: o espaço de trabalho da chave é sempre um a que pertence. |
| `invite_expired` | 410 | O seu convite para o espaço de trabalho expirou. Os pedidos com chave de API não o devolvem, pelo mesmo motivo. |
| `unprocessable_entity` | 422 | O corpo ou os parâmetros de consulta falharam a validação. A mensagem indica o campo e o problema. Consulte [Erros de validação](#erros-de-validação). |
| `rate_limit_exceeded` | 429 | A chave de API esgotou os pedidos da janela atual. Consulte [Limites de pedidos](https://docs.getqr.com/pt/api/rate-limits.md). |
| `internal_server_error` | 500 | Algo correu mal do nosso lado. Tente mais tarde e contacte o suporte se continuar a acontecer. |

## Erros de validação

Quando o corpo ou os parâmetros de consulta falham a 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"
  }
}
```

Os campos aninhados usam notação de pontos, por exemplo `link.url`.

## Tratar erros

* Decida com base em `error.code` e não em `error.message`.
* Não repita erros `4xx` sem alterações: corrija primeiro o pedido. As exceções são um `409` por um pedido ainda em curso e `429`.
* Perante um `429`, aguarde o número de segundos indicado no cabeçalho `Retry-After`. Consulte [Limites de pedidos](https://docs.getqr.com/pt/api/rate-limits.md#quando-ultrapassa-o-limite).
* Repita os erros `5xx` com espera exponencial.

## Problemas comuns

> [accordion] Todos os pedidos devolvem 404 "This endpoint is not available."
>
> A API está em versão beta e ainda não está ativada para o seu espaço de trabalho.

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

> [accordion] 403 "Access denied: This account does not have an active subscription."
>
> A subscrição do dono do espaço de trabalho terminou. A chave de API volta a funcionar assim que o dono renovar a subscrição.

> [accordion] 403 "API access is not available for this role."
>
> A sua função no espaço de trabalho é visualizador. Só o dono do espaço de trabalho e os editores podem utilizar a API.

## Próximos passos

> [card] [Limites de pedidos](https://docs.getqr.com/pt/api/rate-limits.md)

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


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