Erros

Toda falha responde com o mesmo formato e um code estável. Escreva o tratamento de erro em cima do código: a mensagem é destinada a pessoas e pode ser reescrita a qualquer momento.

O formato

O campo details aparece quando há algo por campo a corrigir: em validation_error, um item por campo recusado; em review_required, o que ajustar no texto. O campo request_id identifica a requisição no suporte.

{
  "error": {
    "code": "insufficient_balance",
    "message": "O saldo não cobre este envio.",
    "status": 402,
    "request_id": "req_8f3k2m"
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "Um ou mais campos são inválidos.",
    "status": 422,
    "details": [
      {
        "field": "to",
        "message": "Número fora do padrão +55DDDNÚMERO."
      }
    ],
    "request_id": "req_2c7v9q"
  }
}

Códigos

A mesma lista está versionada em GET /v1/errors, para o seu código ler em tempo de execução.

validation_errorHTTP 422

Parâmetros inválidosUm ou mais campos não passaram na validação. O campo details lista cada problema.

invalid_requestHTTP 400

Requisição malformadaO corpo não é um JSON válido ou o content-type não é aceito.

authentication_requiredHTTP 401

Autenticação obrigatóriaEnvie Authorization: Bearer <token> obtido em POST /v1/auth/token.

invalid_api_keyHTTP 401

Chave de API inválidaA chave não existe, foi revogada ou pertence a outro ambiente.

invalid_tokenHTTP 401

Token inválidoO token Bearer não foi reconhecido. Gere um novo em POST /v1/auth/token.

token_expiredHTTP 401

Token expiradoO token Bearer venceu (validade de 48 horas). Gere um novo.

forbiddenHTTP 403

Sem permissãoA credencial não pode executar esta operação.

identity_requiredHTTP 403

Titular não verificadoEnvios em produção exigem o cadastro do titular (nome, CPF e data de nascimento) concluído no console e não recusado na verificação. Nada foi cobrado.

not_foundHTTP 404

Não encontradoO recurso não existe ou não pertence a este workspace.

conflictHTTP 409

ConflitoA mesma Idempotency-Key foi usada com um corpo diferente, ou o recurso mudou desde a leitura.

review_requiredHTTP 409

Envio precisa de confirmaçãoA análise automática não aprovou o texto, então o envio iria para revisão manual em vez de sair na hora. details traz o que ajustar. Corrija o texto, use um modelo aprovado ou repita a requisição com accept_review: true para aceitar a revisão. Nada foi cobrado.

insufficient_balanceHTTP 402

Saldo insuficienteO workspace não tem créditos para este envio. Recarregue via PIX no console. Nada foi enviado.

rate_limitedHTTP 429

Limite de requisiçõesAguarde o tempo indicado em Retry-After antes de tentar novamente.

provider_unavailableHTTP 503

Operadora indisponívelNão conseguimos aceitar o envio: nada foi enfileirado e nada foi cobrado. Repita a requisição com a mesma Idempotency-Key.

internal_errorHTTP 500

Erro internoFalha inesperada. Informe o request_id ao suporte.

Quando repetir

Em 429 rate_limited, o header Retry-After informa quantos segundos esperar; os SDKs expõem esse valor em error.retryAfter e error.retry_after. Em 503 provider_unavailable, nada foi enfileirado e nada foi cobrado: repita a requisição com a mesma Idempotency-Key. Uma vez que o envio tenha sido aceito com 202, as retentativas até a operadora são nossas — você não precisa repetir nada.