Referência de Erros

Todos os erros da API qr3.app seguem o RFC 7807 Problem Details com Content-Type: application/problem+json.

{
  "type": "https://docs.qr3.app/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "QR code qr_xxx not found"
}

`errors/validation`

HTTP 422 Unprocessable Entity

Os dados de entrada não passaram na validação do esquema. A resposta contém um array errors com detalhes específicos de cada campo.

{
  "type": "https://docs.qr3.app/errors/validation",
  "title": "Validation Error",
  "status": 422,
  "detail": "Request body validation failed",
  "errors": [
    { "field": "url", "message": "Invalid URL format" }
  ]
}

Causas: Campos obrigatórios ausentes, tipos de dados incorretos, valores fora do intervalo permitido, formato de URL inválido.

`errors/bad-request`

HTTP 400 Bad Request

O corpo não é um JSON válido, embora Content-Type: application/json esteja definido (por exemplo, uma vírgula no final, um corpo truncado ou vazio).

`errors/authentication`

HTTP 401 Unauthorized

A chave de API está ausente, formatada incorretamente, expirada ou revogada.

Correção: Verifique se o cabeçalho Authorization: Bearer qr3_sk_... está presente e se a chave está ativa.

`errors/unauthorized`

HTTP 401 Unauthorized

Um webhook de entrada (POST /v1/webhooks/clerk, POST /v1/webhooks/eu-registry) foi chamado sem uma assinatura ou segredo válido. Uma chave de API ausente ou inválida responde com errors/authentication em vez disso.

`errors/authorization`

HTTP 403 Forbidden

A chave de API é válida, mas não possui o escopo ou a permissão necessária.

`errors/forbidden`

HTTP 403 Forbidden

O recurso existe, mas pertence a outro Workspace ou a outra organização.

`errors/document-immutable`

HTTP 403 Forbidden

Um documento de DPP enviado com is_immutable não pode ser excluído.

`errors/not-found`

HTTP 404 Not Found

O recurso solicitado não existe ou foi excluído.

`errors/conflict`

HTTP 409 Conflict

Já existe um recurso com o mesmo identificador exclusivo (por exemplo, slug duplicado ou colisão de Idempotency-Key).

`errors/subscription-exists`

HTTP 409 Conflict

POST /v1/billing/checkout foi chamado, embora a organização já possua uma assinatura. Em vez disso, altere o plano no portal de faturamento.

`errors/rate-limited`

HTTP 429 Too Many Requests

O limite de requisições por minuto da chave de API foi excedido. A resposta contém os cabeçalhos Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset.

`errors/rate-limit`

HTTP 429 Too Many Requests

Um limite de requisições específico do recurso foi excedido (por exemplo, 200 códigos QR por dia por Workspace).

`errors/plan-limit`

HTTP 422 Unprocessable Entity

O seu plano atual não permite esta ação (por exemplo, cota de DPPs ou códigos dinâmicos esgotada, lote muito grande, excesso de Workspaces ou membros da equipe). Upgrade necessário.

`errors/invalid-file-type`

HTTP 400 Bad Request

O arquivo enviado possui um tipo que o endpoint não aceita, ou o seu conteúdo não corresponde ao Content-Type declarado.

`errors/file-too-large`

HTTP 413 Payload Too Large

O arquivo enviado excede o limite de tamanho do plano ou do endpoint.

`errors/storage-limit-exceeded`

HTTP 422 Unprocessable Entity

O upload excederia o armazenamento total do Workspace ou do DPP.

`errors/not-configured`

HTTP 503 Service Unavailable

Um serviço ou configuração necessária está ausente (por exemplo, Stripe não configurado, chave de API do Web Risk não definida).

`errors/unsafe-url`

HTTP 422 Unprocessable Entity

A URL foi rejeitada porque foi classificada como insegura pelo Google Web Risk (malware, phishing, engenharia social).

`errors/url-flagged`

HTTP 422 Unprocessable Entity

Reservado para URLs que foram posteriormente classificadas como inseguras durante a varredura periódica.

`errors/already-submitted`

HTTP 409 Conflict

Envio duplicado — por exemplo, já foi enviado um NPS para este Workspace este mês.

`errors/unprocessable-entity`

HTTP 422 Unprocessable Entity

Uma ação de administrador não é permitida (por exemplo, personificar outro superadmin). Apenas os endpoints de superadmin retornam este tipo.

`errors/request-error`

HTTP 4xx Client Error

Fallback para erros do cliente sem um tipo mais específico; o status está na resposta. A API atualmente não possui nenhum caminho conhecido que o retorne.

`errors/internal`

HTTP 500 Internal Server Error

Ocorreu um erro inesperado no servidor. Por favor, tente a requisição novamente. Se o problema persistir: [email protected].