Docs Entrar na plataforma

Fundamentos

Erros

Todo erro volta no mesmo envelope, com um código estável para o seu sistema e uma mensagem em português para quem opera.

O envelope

Qualquer resposta de erro tem um array errors. Cada item tem um code — estável, feito para o seu código decidir o que fazer — e uma message em português, feita para mostrar a uma pessoa.

422 · regra de negócio 
{
  "errors": [
    {
      "code": "ANTICIPATION_INVALID_DUE_DATE",
      "message": "O vencimento da nota deve ser de pelo menos 5 dias a partir de hoje"
    }
  ]
}
400 · validação 
{
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "message": "supplier: Campo obrigatório"
    },
    {
      "code": "VALIDATION_ERROR",
      "message": "Valor mínimo de R$ 500,00"
    }
  ]
}

Erros de validação

Um corpo inválido responde 400 com um item por problema, todos com code: "VALIDATION_ERROR". O campo não vem separado: quando ajuda, ele aparece no começo da mensagem (supplier: Campo obrigatório, Vencimento: Data inválida (use o formato AAAA-MM-DD)).

Campos que a API não conhece são ignorados sem erro. Confira o nome de cada campo na referência do endpoint.

Status HTTP

StatusSignificaRetentar?
400 O corpo, o header ou o parâmetro não passou na validação. Não. Corrija a requisição.
401 Chave ausente, inválida, revogada ou expirada. Não. Troque a chave.
403 Chave sem escopo, ou responsável sem permissão. Não. Ajuste escopo ou responsável.
404 Rota ou operação não encontrada. Não.
409 Conflito: nota já em andamento, operação que mudou de estado durante a chamada, ou conflito de idempotência. Depende do código — veja nota duplicada e Idempotência.
413 Arquivo acima de 10 MB. Não. Envie arquivo menor.
422 A requisição é válida, mas a regra de negócio recusou. Não sem mudar os dados.
429 Limite de requisições atingido. Sim, depois do Retry-After.
500 Erro inesperado da Oneos. Sim, com espera crescente e a mesma Idempotency-Key.

Os códigos de cada endpoint estão nas páginas de criar, cancelar e consultar; os de chave, em Autenticação.

Dados estruturados

Alguns erros trazem, além de errors, um array details com o dado que o seu sistema precisa para agir — hoje, o anticipationId da operação existente no 409 PRE_AUTH_DUPLICATE_INVOICE. Leia o id de details, nunca da message.

Retentativas seguras

  • Retente só 429, 5xx e falhas de rede (timeout, conexão recusada).
  • Espere o Retry-After no 429; nos outros casos, espere cada vez mais (1 s, 2 s, 4 s…).
  • Ao criar pré-autorização, repita a mesma Idempotency-Key: se a primeira chamada tinha dado certo e só a resposta se perdeu, a Oneos devolve a operação original em vez de criar outra.
Esc