SonaCORE
Agendar conversa

Erros

Duas formas, e como distinguir uma da outra.

Erros deliberados devolvem um código e uma mensagem. Falhas de validação de esquema devolvem a forma por campo do próprio framework. Trate as duas, porque elas chegam nos mesmos códigos de status e um cliente que só interpreta uma vai descartar em silêncio o detalhe da outra.

O envelope da casa

Todo erro que a API levanta de propósito tem esta forma. O campo error é um código estável e legível por máquina; ramifique nele. O message é para uma pessoa lendo um log; não faça parse dele.

409
{
  "error": "IDEMPOTENCY_KEY_REUSED",
  "message": "Idempotency key already used with a different request body"
}

A forma de validação

Uma requisição que falha na validação de esquema antes de chegar a qualquer handler devolve o detalhe por campo do framework, sob detail e não sob error. Essa é a única resposta de erro que os artefatos de contrato declaram, e é por isso que é a que você vai ver na referência gerada.

422
{
  "detail": [
    {
      "loc": ["body", "amount", "value"],
      "msg": "Input should be a valid integer",
      "type": "int_type"
    }
  ]
}
Detecte a forma, não a presuma
As duas formas podem chegar com um 422. Verifique error primeiro e caia para detail; se você ramificar apenas no status, vai entregar aos seus próprios chamadores um motivo vazio.

Códigos de status

StatusSignificaCausa típica
400validaçãoA requisição está malformada, ou um valor não é aceitável para esta operação.
401autenticaçãoToken ausente, malformado ou expirado, ou um cliente que o gateway não reconhece. Veja Autenticação.
403escopoO token é válido e falta nele um escopo exigido.
404não encontradoO recurso não existe, ou existe e não é seu. Deliberadamente indistinguível.
409conflitoUm conflito com o estado existente: uma chave de idempotência reusada com corpo diferente, algo já resolvido, uma transição concorrente que perdeu.
422não processávelBem formada e não processável: uma violação de esquema, ou uma regra que rejeita a requisição pelo mérito dela.
500servidorCulpa nossa. O corpo nunca contém stack trace nem mensagem crua de exceção. Repita escritas idempotentes com a mesma chave.
503dependênciaUma dependência de que o caminho de escrita precisa está indisponível. A obrigação não foi criada; repita.

Códigos documentados

Estes são os códigos cujo status e gatilho podemos apontar em uma fonte. Não é o conjunto completo: a API devolve muitos mais, e ainda não publicamos um catálogo com a promessa de estabilidade que um catálogo implica. Trate um código não reconhecido como você trataria qualquer código não reconhecido: registre, exponha o status, e não quebre.

CódigoStatusGatilho
IDEMPOTENCY_KEY_REUSED409A mesma Idempotency-Key foi repetida com um corpo de requisição diferente. Repetir com um corpo idêntico devolve o resultado original.
INSUFFICIENT_SCOPE403Falta no token um escopo que a rota exige. A mensagem nomeia qual.
UNMAPPED_ACCOUNT404Chegou evidência para uma coordenada de destino que não está vinculada a nenhuma conta. Vincule um meio de pagamento primeiro.
DUPLICATE_EVIDENCE409Este fato de liquidação externo já foi ingerido.
TEMPLATE_NOT_FOUND404Não existe esse modelo de transferência.
TEMPLATE_VERSION_MISMATCH409O modelo existe em uma versão diferente da que você fixou. Fixar a versão é como você evita ser surpreendido por uma mudança no modelo.
TEMPLATE_PARAMS_INVALID400Um parâmetro que o modelo não define, ou um obrigatório que faltou.
TEMPLATE_UNPROCESSABLE422Os parâmetros estão bem formados e o modelo os recusa, por exemplo uma tarifa de cem por cento.
WEBHOOK_LIMIT_EXCEEDED422Você já tem o número máximo de endpoints de webhook ativos.
INVALID_EVENT_FILTER422Um filtro de webhook que não é nem um tipo de evento exato nem um curinga family.*. Veja Eventos e webhooks.

O que é seguro repetir

← AutenticaçãoPróximo: Eventos e webhooks →