Skip to main content

​
Dois formatos de erro

A API retorna erros em JSON, em um de dois formatos.

​
Erro geral

Um único campo detail com a mensagem:

​
Erro de validação

Um objeto onde cada chave é o campo rejeitado e o valor é a lista de problemas daquele campo:
As mensagens são retornadas em português (Brasil). Não use o texto da mensagem como regra de negócio — trate pelo código de status e, quando for erro de validação, pelo nome do campo.

​
Códigos de status

​
Casos que confundem

  • 401 — a API não sabe quem você é: o token está ausente, malformado ou expirou.
  • 403 — a API sabe quem você é, mas sua chave não tem o escopo necessário. Por exemplo, chamar POST /public_api/products/ com um token que só tem read.
Os escopos de cada endpoint estão indicados na própria página de referência.
Todos os endpoints filtram pelos dados da sua conta. Consultar um recurso que pertence a outro produtor retorna 404, não 403 — isso é intencional, para não revelar a existência do recurso.
O token tem validade limitada (campo expires_in) e não existe endpoint de renovação. Ao receber 401 durante um processamento longo, solicite um novo token e repita a requisição.
Respostas 5xx não são armazenadas pela idempotência. Repita a requisição com o mesmo X-Idempotency-Key: se a cobrança original tiver sido criada, você recebe a resposta original em vez de uma duplicata.
POST /public_api/payments/ rejeita pix, pix_auto e boleto com 400 no campo paymentMethod quando o produtor não tem conta Cakto Banking com abertura concluída, ativa, principal e fora de encerramento — é nela que esses métodos liquidam. credit_card e threeDs ficam fora desse gate — cartão não liquida nessa conta —, mas exigem os campos próprios do cartão (card e antifraud_profiling_attempt_reference), então trocar só o paymentMethod não é um payload válido.Não é erro de payload: nenhum ajuste nos campos de Pix ou boleto resolve, o bloqueio é a conta. Conclua ou regularize a abertura da conta no Painel Cakto. Detalhes em Pré-requisitos.

​
Próximos passos

Autenticação

Escopos, tokens e expiração

Limites de Requisição

Como reagir ao 429