Corrija erros da API da CodeQR: 401, 403, 404, 409 e 429
Cada erro da API da CodeQR com causa e correção — chave inválida, Bearer ausente, permissão faltando, workspace errado, chave duplicada, 405 no PATCH, 429.
Todo erro que a API da CodeQR devolve tem a mesma forma e uma mensagem fixa (em inglês). Esta página lista os que você vai encontrar, o que causou cada um e a correção — as mensagens abaixo foram capturadas ao vivo em 2026-08-17.
Disponibilidade
- Plano: todos os planos. Os limites de requisições variam por plano (veja 429).
- Onde: qualquer chamada a
https://api.codeqr.io, e as mesmas mensagens exibidas por Zapier, Make, n8n ou Pipedream quando um passo falha (eles mostram omessage, às vezes com um texto próprio na frente).
Antes de começar
O corpo do erro é:
{
"error": {
"code": "unauthorized",
"message": "Unauthorized: Invalid API key.",
"doc_url": "https://docs.codeqr.io/api-reference/errors#unauthorized"
}
}code é estável — compare por ele no código; message é para pessoas. Status HTTP por código: bad_request e unprocessable_entity → 400, unauthorized → 401, forbidden e exceeded_limit → 403, not_found → 404, conflict → 409, rate_limit_exceeded → 429, internal_server_error → 500. (Erros de validação vêm como 400, não 422.)
Solução de problemas
401 — Unauthorized: Login required.
Nenhum cabeçalho Authorization chegou à API. Acrescente Authorization: Bearer codeqr_…; se já enviou, confira se o seu cliente HTTP ou proxy não está descartando o cabeçalho (algumas ferramentas removem Authorization em redirecionamentos, então chame https://api.codeqr.io direto, sem um alias que redirecione).
401 — Unauthorized: Invalid API key.
A chave não existe: foi apagada, digitada errado, colada com espaço ou quebra de linha, ou pertence a outro ambiente. Crie uma chave nova em Configurações → Chaves de API e cole de novo — a chave completa só aparece uma vez, então uma chave "guardada" que você não consegue mais ver pode ser uma cópia antiga.
401 — Unauthorized: Access token expired.
A chave tinha uma expiração que passou. Crie uma chave nova.
400 (texto puro) — Authorization header misconfigured. Did you forget to add 'Bearer '?
O cabeçalho existe, mas não começa com Bearer . Envie Authorization: Bearer codeqr_… (com o espaço). Zapier e Make acrescentam o prefixo por você; no nó HTTP Request do n8n escolha "Bearer Auth" ou digite o prefixo.
403 — The provided key does not have the required permissions for this endpoint in the project '…'. Having the permission 'links.write' would allow this request to continue.
A chave foi criada Somente Leitura ou Restringido sem aquele recurso. A mensagem diz a permissão que falta (links.write, qrcodes.write, analytics.read, webhooks.write…). Edite a chave (⋮ → Editar Chave de API) para incluí-la, ou crie uma chave nova. Algumas permissões Write só existem para proprietários do workspace.
403 — No permission: You need a higher plan.
O endpoint ou a opção está acima do plano do workspace (API de Events, algumas janelas de analytics, webhooks, webhooks de clique). Faça upgrade ou remova a opção.
403 — You have reached the monthly limit of … links on the … plan. Please upgrade to add more links.
Código exceeded_limit: a cota mensal de links (ou QR codes, páginas, tags, domínios, pastas) do workspace acabou. Espere o próximo ciclo de cobrança, apague o que não precisa ou faça upgrade. Requisições em massa são recusadas por inteiro quando o lote cruzaria o limite.
404 — Project not found. / Link not found.
Workspace errado ou id errado. Chaves são presas a um workspace: um id de link do workspace A não resolve com uma chave do workspace B (a mensagem pode dizer Link does not belong to project ws_…). Use GET /links/info?domain=…&key=… para achar o id no workspace certo.
409 — Duplicate key: this short link already exists.
Aquela key já está em uso naquele domínio. Escolha outra chave, ou omita key para receber uma aleatória. Em requisições em massa só aquele item falha; os demais são criados.
409 — A link with this externalId already exists.
Você já criou um link com aquele externalId — a requisição é uma repetição. Consulte com GET /links/info?externalId=ext_<id> e reaproveite.
400 — Invalid destination URL / invalid_type: url: Required
O campo url está faltando ou não é uma URL completa. Envie https://…; confira espaços no fim das células de planilha e células com só o domínio.
400 — Invalid externalId. Did you forget to prefix it with ext_?
Consultas por id externo recebem o prefixo ext_ (?externalId=ext_row-42); a criação armazena sem o prefixo. Acrescente ext_ só nas leituras.
400 — Invalid tagNames detected: …
O nome da tag não existe no workspace. Crie antes (POST /tags) — e prefira tagIds: enviar tagNames com uma tag existente falha hoje com um erro longo de banco de dados.
405 — Method Not Allowed em PATCH /links/{id}
Atualizações usam PUT. Troque o verbo e mantenha o corpo JSON.
429 — Too many requests.
Mais requisições que o limite por minuto da chave — Free 60, Starter 100, Pro 500, Business 1.000, Scale 10.000. Espere o próximo minuto e reenvie. Observe x-ratelimit-remaining em cada resposta; ignore o retry-after dessas respostas (ele traz um timestamp, não segundos). Agrupe com POST /links/bulk (100 por chamada) em vez de uma chamada por linha.
500 — An internal server error occurred. Please contact our support if the problem persists.
Tente de novo uma vez. Uma chamada reproduz isso hoje: GET /links/count?search=… — conte sem search, ou filtre por tagIds. Se persistir, envie o cabeçalho de resposta x-vercel-id ao suporte.
O Zapier mostra "The app returned …" ou o Make para o cenário
Os dois mostram o message da CodeQR dentro do próprio texto de erro. Ache a mensagem acima; a correção é a mesma. Um 410 vindo de um endpoint do Zapier ou do Make não é erro da CodeQR — é a plataforma cancelando a assinatura de um webhook.