Erros

Todos os erros da API v1 usam o mesmo envelope. O code é estável e deve orientar sua automação. A message é feita para leitura humana e pode receber melhorias sem mudar o código.

A lista de códigos pode crescer com novos recursos. Um cliente bem-comportado conhece os códigos úteis para sua regra de negócio e, quando recebe um código desconhecido, decide pelo status HTTP. Não trate código desconhecido como sucesso.

{
  "error": {
    "code": "validation_error",
    "message": "Corpo ou parâmetros inválidos.",
    "details": [
      {
        "field": "email",
        "message": "value is not a valid email address"
      }
    ],
    "request_id": "0123456789abcdef0123456789abcdef"
  }
}

details só aparece quando há informação estruturada adicional e, quando aparece, é sempre uma lista de objetos. Guarde o request_id ao abrir um chamado, mas nunca registre o header Authorization.

Códigos

Provocar um 401 com curl

A chave abaixo é fictícia:

curl --include \
  --request GET \
  --url "https://api.octosolve.com.br/api/v1/contacts" \
  --header "Authorization: Bearer osk_live_exemplo_ficticio_00000000000000000000000000" \
  --header "Accept: application/json"

Receita para Make ou n8n

1. Configure o módulo ou nó HTTP para não interromper todo o fluxo ao receber status de erro.
2. Separe o caminho de sucesso do caminho em que existe error.code.
3. Em rate_limited, espere conforme Retry-After antes de repetir.
4. Em idempotency_in_progress e service_unavailable, repita com espera crescente e número máximo de tentativas.
5. Em erros 400, 401, 403, 404, 405, 413, 415 e 422, corrija a entrada ou a configuração. Não repita o mesmo pedido sem alteração.
6. Em slot_conflict, consulte a disponibilidade novamente e ofereça outro horário.
7. Em invalid_transition, leia details[0].status_atual e siga a máquina de estados de agendamentos.
8. Em calendar_not_connected, conecte a agenda no painel. Não repita a mesma requisição antes disso.
9. Em conflict e idempotency_conflict, encaminhe para uma regra de negócio ou revisão humana.
10. Para qualquer código desconhecido, use o status HTTP para decidir entre corrigir a entrada, pedir revisão ou tentar novamente.
11. Registre error.code, status e request_id. Não registre a chave da API nem o corpo se ele contiver dados pessoais desnecessários.