Entenda o envelope, os status HTTP e todos os códigos de erro da API pública da OctoSolve.

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.

{
  "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. Guarde o request_id ao abrir um chamado, mas nunca registre o header Authorization.

Códigos

Status HTTP	Código	Quando acontece
401	`unauthorized`	Chave ausente, malformada, inexistente, revogada, suspensa ou vencida
403	`forbidden_plan`	O plano não inclui acesso à API
403	`forbidden_scope`	Uma chave `read` tentou executar `POST` ou `PATCH`
403	`account_suspended`	A conta está suspensa por pendência de pagamento
404	`not_found`	Rota ou recurso não encontrado, inclusive contato de outra conta
405 ou 422	`validation_error`	Método não aceito, parâmetro inválido ou corpo que não atende ao schema
400	`invalid_cursor`	Cursor inválido ou reutilizado com filtros diferentes
429	`rate_limited`	Limite por minuto, hora, dia ou proteção de tentativas por IP atingido
409	`conflict`	Conflito de negócio, como telefone de contato duplicado
409	`idempotency_conflict`	A mesma `Idempotency-Key` foi reutilizada com outro corpo, método ou rota
409	`idempotency_in_progress`	A requisição original com a chave de idempotência ainda está em andamento
413	`payload_too_large`	Corpo maior que 64 KB
415	`unsupported_media_type`	Corpo enviado sem `application/json`
500	`internal_error`	Erro interno inesperado, sem detalhes técnicos na resposta
503	`service_unavailable`	Dependência obrigatória indisponível, como o controle de limites

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

Configure o módulo ou nó HTTP para não interromper todo o fluxo ao receber status de erro.
Separe o caminho de sucesso do caminho em que existe error.code.
Em rate_limited, espere conforme Retry-After antes de repetir.
Em idempotency_in_progress e service_unavailable, repita com espera crescente e número máximo de tentativas.
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.
Em conflict e idempotency_conflict, encaminhe para uma regra de negócio ou revisão humana.
Registre error.code, status e request_id. Não registre a chave da API nem o corpo se ele contiver dados pessoais desnecessários.

Erros

Erros

Códigos

Provocar um 401 com curl

Receita para Make ou n8n

On this page