Erros
Toda resposta de erro usa application/problem+json (RFC 9457):
{
"type": "https://docs.conectzap.app/errors/instance_not_connected",
"title": "Instância não conectada",
"status": 409,
"code": "instance_not_connected",
"detail": "…",
"requestId": "…",
"errors": [{ "path": "…", "message": "…" }]
}
-
codeé estável e independe do idioma: programe pelocode, nunca pelotitleou pelodetail. typeé o link para a página do código, nesta documentação.-
title,detaileerrors[].messageseguemAccept-Language(pt-BR,enoues). -
errors[]aparece em erros de validação, com opathde cada campo. - Informe o
requestIdao falar com o suporte.
Quando tentar de novo
Repita só o que é transitório: 429, 503 e 500, além de
409 instance_paused e 409 conflict quando vierem com
Retry-After. Respeite o Retry-After e use backoff exponencial com
jitter. Nas operações que criam efeitos, mande a mesma Idempotency-Key na repetição
para não duplicar. Os demais 4xx pedem correção da requisição. Veja
Limites.
Códigos
| Código | Status | Título |
|---|---|---|
validation_failed | 400 | Requisição inválida |
unauthenticated | 401 | Não autenticado |
forbidden | 403 | Acesso negado |
not_found | 404 | Recurso não encontrado |
method_not_allowed | 405 | Método não permitido |
conflict | 409 | Conflito |
plan_limit_reached | 409 | Limite do plano atingido |
instance_not_connected | 409 | Instância não conectada |
instance_paused | 409 | Instância em pausa |
instance_busy | 429 | Instância ocupada |
message_not_found | 404 | Mensagem não encontrada |
idempotency_key_reused | 422 | Idempotency-Key reutilizada |
rate_limited | 429 | Limite de requisições excedido |
payload_too_large | 413 | Conteúdo grande demais |
unsupported_media_type | 415 | Tipo de mídia não suportado |
invalid_signature | 403 | Assinatura inválida |
upload_expired | 410 | Prazo de envio expirado |
already_uploaded | 409 | Arquivo já enviado |
media_type_mismatch | 422 | Tipo de mídia divergente |
media_not_found | 404 | Mídia não encontrada |
media_unavailable | — | Mídia indisponível |
media_fetch_failed | — | Falha ao baixar a mídia |
voice_note_requires_ogg | 400 | Mensagem de voz exige OGG/Opus |
provider_unavailable | 503 | Provedor indisponível |
tenant_migrating | 503 | Migração em andamento |
service_unavailable | 503 | Serviço indisponível |
internal_error | 500 | Erro interno |