Toda resposta de erro tem o mesmo formato. Código de status + code legível por máquina + mensagem para humanos + field opcional apontando a entrada com problema.
{
"success": false,
"error": "Content length (5000) exceeds maximum allowed (4296 characters).",
"code": "CONTENT_TOO_LONG",
"field": "content"
}
| Status | Significado |
|---|
200 | Sucesso |
400 | Erro de validação — corrija a entrada e tente de novo |
401 | Cabeçalho de autenticação ausente ou incorreto |
402 | Gateway de chaves de usuário: falta o plano Studio ou os créditos de API acabaram |
404 | Endpoint não encontrado |
413 | Corpo grande demais (>10 MB) ou, no gateway de chaves de usuário, um arquivo gerado com mais de 10 MB (output_too_large) |
422 | O motor não conseguiu produzir um QR legível nem depois da correção automática (QR_UNSCANNABLE), ou a saída passaria do orçamento (OUTPUT_TOO_COMPLEX) |
429 | Limite de requisições — veja Retry-After |
500 | Interno — registre e tente de novo |
503 | Servidor ocupado (muitas renderizações grandes simultâneas) ou provedores de IA sem capacidade (AI_QUOTA_EXCEEDED) |
| Código | Significado |
|---|
MISSING_REQUIRED_FIELD | content (ou prompt nos endpoints de IA) está vazio |
CONTENT_TOO_LONG | Conteúdo codificado com mais de 4296 caracteres (máximo teórico de um QR) |
INVALID_JSON | O corpo não pode ser interpretado como JSON |
INVALID_HEX | Uma cor não está no formato #RGB, #RRGGBB ou #RRGGBBAA |
INVALID_FIELD_VALUE | Genérico — field indica qual |
VALUE_OUT_OF_RANGE | Campo numérico fora dos limites documentados |
LOW_CONTRAST | Primeiro plano vs fundo abaixo de 4:1; o motor não consegue corrigir automaticamente |
LOGO_TOO_LARGE | logoSizePercent acima de 25 com ECC abaixo de H |
FILE_TOO_LARGE | Envio multipart com mais de 10 MB |
MULTIPART_CONFIG_MISSING | Campo config ausente na requisição form-data |
| Código | Significado |
|---|
UNAUTHORIZED | X-RapidAPI-Proxy-Secret ausente ou incorreto |
INVALID_INTERNAL_SIGNATURE | O HMAC do BFF não passou na verificação |
INTERNAL_TS_EXPIRED | Timestamp do BFF fora da janela de ±60s |
LLM_API_KEY_INVALID | A chave do seu provedor (só no endpoint de IA do marketplace) |
O gateway https://qr-branding.com/api/v1/* (Chaves de API do usuário) adiciona seus próprios códigos, em minúsculas, com o mesmo envelope success / error / code:
| Status | Código | Significado |
|---|
400 | invalid_body | Não foi possível interpretar o corpo |
401 | missing_api_key | Falta o cabeçalho X-API-Key |
401 | invalid_api_key | Chave não reconhecida, revogada ou malformada |
402 | studio_required | A chave é válida, mas a conta não tem um pacote Studio ativo. Inclui os links docs e pricing |
402 | out_of_api_credits | Geração com IA nas nossas chaves sem créditos Studio restantes. Inclui os links docs e pricing |
413 | payload_too_large | Corpo com mais de 1 MiB |
413 | output_too_large | O arquivo gerado tem mais de 10 MB. Peça PNG ou um outputWidth menor |
415 | multipart_not_supported | O gateway só aceita JSON |
POST /api/checkout (o botão de compra em /pricing) responde { "error": "withdrawal_waiver_required" } quando falta o consentimento:
| Status | Código | Significado |
|---|
400 | withdrawal_waiver_required | A caixa anterior ao pagamento (consentimento e renúncia ao direito de arrependimento) não foi marcada. Veja Preços e créditos |
| Código | Significado |
|---|
AI_GENERATION_FAILED | O LLM não devolveu nenhuma configuração utilizável — tente um prompt mais claro |
AI_REQUEST_TIMEOUT | Nenhum provedor da cadeia de reserva respondeu dentro do prazo total de 45 s (cada um tem no máximo 20 s). Responde 503; tente de novo em instantes |
AI_QUOTA_EXCEEDED | Todos os provedores da cadeia de reserva recusaram por cota ou limite de gastos. Responde 503; tentar de novo na hora não adianta, tente mais tarde |
AI_CONFIG_INVALID | O LLM devolveu uma configuração que o motor rejeitou (raro; tente de novo com menos criatividade) |
INVALID_LLM_PROVIDER | Só no marketplace — llmProvider não está em openai anthropic google mistral cohere groq xai deepseek qwen local |
INVALID_LLM_MODEL | Só no marketplace — llmModel não tem formato de ID de modelo |
| Código | Significado |
|---|
OUTPUT_TOO_COMPLEX | O design produziria um SVG ou PDF com mais de 20 MB, ou uma tela raster interna com mais de 5120 px por lado. O tamanho de um SVG cresce com o número de módulos: um modelo com uma URL curta ocupa ~1,5 MB e com uma URL de 300 caracteres ~17 MB. Exporte em PNG, encurte o conteúdo ou use formatos de módulo mais simples |
| Código | Significado |
|---|
INTERNAL_ERROR | Inesperado — informe-nos com o id da requisição |
QR_GENERATION_FAILED | O próprio motor de renderização lançou uma exceção. Inclui o campo problemático quando ele é conhecido |
SERVER_BUSY | Renderizações simultâneas em alta resolução demais. Aguarde e tente de novo |
| Campo | Restrição |
|---|
content | 1–4296 caracteres |
prompt (IA) | 1–10000 caracteres |
creativity (IA) | 0.0–1.0 |
pixelsPerModule | 1–100 |
outputWidth / outputHeight | 64–4096 |
logoSizePercent | 3–40 (o motor aplica um teto flexível de 25 com ECC H) |
moduleScale | 0.5–1.0 |
moduleSizeVariation | 0.0–0.15 (teto flexível; qualquer valor acima disso impede a leitura) |
qrShapeRadius | 0–50 |
| Tamanho do arquivo de logo / fundo | ≤ 10 MB |
| Tipos de imagem de logo / fundo | PNG, JPG, GIF, BMP, WebP |
| Documento SVG / PDF | ≤ 20 MB (OUTPUT_TOO_COMPLEX) |
| Arquivo pelo gateway de chaves de usuário | ≤ 10 MB (output_too_large) |