PicChat

Guias

Códigos HTTP e erros

Formato

Os erros vêm em JSON com o status, uma mensagem para pessoas e um errorCode estável para o seu código tratar:

{
  "statusCode": 403,
  "error": "permission_denied",
  "message": "Seu usuário (Ana Lima) não tem permissão para Inbox › ver.",
  "required": ["inbox:read"],
  "errorCode": "API_V1_PERMISSION_DENIED"
}

Trate pelo errorCode, não pela message — o texto pode mudar.

Códigos HTTP

Código Significa
200 Consulta ok
201 Criado ou aceito (POST)
400 Parâmetro inválido (ex.: data mal formada, campo extra no corpo do disparo, lote acima do limite do plano)
403 Sem permissão, canal fora do escopo, account_id de outra conta ou automação inativa
404 Recurso não encontrado na conta
422 Corpo não passou na validação (tipo ou formato errado)
498 Token ausente, inválido ou revogado
500 Erro interno — tente de novo com espera; se persistir, fale com o suporte

498 não é um código HTTP padrão: alguns clientes HTTP mostram como "Unknown". Trate como o 401 de outras APIs.

errorCode mais comuns

errorCode Status Quando
API_TOKEN_INVALID 498 Token ausente, malformado ou de conta inexistente
API_TOKEN_REVOKED 498 Token excluído no painel
API_V1_PERMISSION_DENIED 403 O grupo do usuário não libera a consulta (required lista a permissão)
API_V1_CHANNEL_OUT_OF_SCOPE 403 O recurso é de um canal fora dos canais do usuário
API_V1_TOKEN_WITHOUT_USER 403 Token sem usuário — gere um token novo por um usuário
API_ACCOUNT_ID_NOT_IN_TOKEN 403 account_id informado não é o da conta do token
API_V1_DATE_PARAM_INVALID 400 Data inválida em from, to, updated_from ou updated_to (errorParams.param diz qual)
API_V1_*_NOT_FOUND 404 O item pedido não existe na conta (ex.: API_V1_TICKET_NOT_FOUND)

Validação (422)

Quando o corpo de um POST não passa na validação, message traz a lista do que está errado:

{
  "statusCode": 422,
  "message": ["mobilephone must be a string"],
  "error": "Unprocessable Entity"
}

Comportamentos a conhecer

  • GET /contacts/find com contato inexistente responde 200 com corpo vazio.
  • Listagens aninhadas (/v1/tickets/{id}/messages, /v1/contacts/{id}/tickets, /v1/lists/{id}/contacts) com o pai inexistente devolvem lista vazia, não 404.
  • POST /automations/enrollments responde 201 ao enfileirar; problemas na automação ou no contato aparecem depois, nas mensagens (veja Disparar mensagens).