Erros

Todo erro — inclusive os que não previmos — tem a mesma forma:

{
  "error": {
    "type": "invalid_request_error",
    "code": "amount_below_minimum",
    "message": "O valor está abaixo do mínimo permitido.",
    "details": {}
  }
}

Baseie a sua lógica no code. Ele é contrato e não muda. A message é escrita para gente ler e pode ser reescrita a qualquer momento — inclusive para ficar melhor. Quando isso acontece, um if que compara a mensagem para de funcionar sem avisar.

As sete famílias

O type responde de quem é o problema e o que fazer. É por ele que você decide o comportamento; o code diz qual mensagem mostrar.

`type`	De quem é	O que fazer
`authentication_error`	Sua chave	Troque a chave. Não repita
`permission_error`	Seu escopo	Gere uma chave com o escopo certo. Não repita
`invalid_request_error`	Sua chamada	Corrija os dados. Repetir igual dá o mesmo erro
`idempotency_error`	Sua chave de idempotência	Chave nova, ou repita em instantes
`not_found_error`	O recurso	Confira o código. Não repita
`rate_limit_error`	Ritmo	Espere o `Retry-After` e repita
`api_error`	Nosso	Repita com a mesma `Idempotency-Key`. Não reescreva a chamada

A divisão que importa na prática: invalid_request_error se corrige mudando a chamada, authentication_error trocando a chave, e api_error é nosso — repita, não reescreva.

`details`

details é sempre objeto, mesmo vazio. Em validation_failed, ele traz os campos recusados e as mensagens de cada um:

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "Alguns campos não passaram na validação.",
    "details": {
      "amount": ["O valor deve ser um inteiro em centavos (R$ 10,00 = 1000)."],
      "customer.name": ["O campo nome é obrigatório."]
    }
  }
}

Em insufficient_scope, ele traz required_ability e a lista de abilities que a chave tem.

Catálogo de códigos

Todos são estáveis. Se um código novo aparecer, ele entra nesta tabela — nenhum destes muda de significado.

`code`	HTTP	`type`	O que fazer
`missing_api_key`	401	`authentication_error`	Envie `Authorization: Bearer sk_…`
`invalid_api_key`	401	`authentication_error`	Confira se copiou a chave inteira e o ambiente certo
`revoked_api_key`	401	`authentication_error`	A chave existiu e foi desligada. Gere outra em Desenvolvedores
`expired_api_key`	401	`authentication_error`	Gere outra em Desenvolvedores
`insufficient_scope`	403	`permission_error`	A chave é válida, falta o escopo. `details.required_ability` diz qual
`resource_not_found`	404	`not_found_error`	O recurso não existe — ou é de outra conta
`idempotency_key_too_long`	400	`invalid_request_error`	Encurte a chave para 255 caracteres
`idempotency_key_reused`	409	`idempotency_error`	A chave já foi usada com outro corpo. Use uma chave nova
`idempotency_key_in_progress`	409	`idempotency_error`	A primeira ainda está em voo. Repita em instantes
`validation_failed`	422	`invalid_request_error`	`details` traz campo → mensagens. Corrija e reenvie
`amount_below_minimum`	422	`invalid_request_error`	Valor abaixo do mínimo permitido
`amount_above_maximum`	422	`invalid_request_error`	Valor acima do máximo permitido
`items_do_not_match_amount`	422	`invalid_request_error`	A soma de `quantity * amount` dos itens tem que bater com `amount`
`seller_not_approved`	422	`invalid_request_error`	Nada na chamada resolve. O caminho é o painel
`provider_rejected`	422	`invalid_request_error`	Confira os dados do comprador e o valor
`charge_not_refundable`	422	`invalid_request_error`	Só cobrança paga é estornável
`exceeds_remaining`	422	`invalid_request_error`	Peça no máximo o saldo estornável, ou omita `amount`
`refund_window_closed`	422	`invalid_request_error`	Passaram-se 90 dias desde o pagamento. Não há retentativa
`refund_disabled`	422	`invalid_request_error`	Estorno não habilitado para a conta. Fale com o suporte
`too_many_requests`	429	`rate_limit_error`	Espere o `Retry-After` e repita
`provider_rate_limited`	429	`rate_limit_error`	Limite do provedor. Repita com backoff
`internal_error`	500	`api_error`	Repita com a mesma `Idempotency-Key`
`provider_unavailable`	502	`api_error`	Repita com a mesma `Idempotency-Key` — a cobrança pode ter sido criada
`platform_unavailable`	503	`api_error`	É problema nosso. Repita depois; nada na chamada resolve

Tratando na prática

$erro = $resposta->json('error');

match ($erro['type']) {
    'api_error', 'rate_limit_error' => $this->repetir($chaveIdempotencia),
    'authentication_error', 'permission_error' => $this->alertarOperacao($erro['code']),
    default => $this->registrarFalhaDoPedido($erro['code'], $erro['details']),
};

const { error } = await resposta.json();

switch (error.type) {
  case 'api_error':
  case 'rate_limit_error':
    return repetir(chaveIdempotencia);
  case 'authentication_error':
  case 'permission_error':
    return alertarOperacao(error.code);
  default:
    return registrarFalhaDoPedido(error.code, error.details);
}

erro = resposta.json()["error"]

if erro["type"] in ("api_error", "rate_limit_error"):
    repetir(chave_idempotencia)
elif erro["type"] in ("authentication_error", "permission_error"):
    alertar_operacao(erro["code"])
else:
    registrar_falha_do_pedido(erro["code"], erro["details"])

Registre code, type e o horário da chamada no seu log. São esses três que permitem localizar a requisição do nosso lado quando você abre um chamado.

Veja também

Repetir com segurança

A matriz de qual código merece retry.

Limites de requisição

Como não chegar no 429.

Ficou algo de fora? Escreva para suporte@usevext.com. Se o assunto for uma chamada específica, informe o horário dela; se for uma entrega de webhook, informe o X-Vext-Delivery — é por ele que localizamos a tentativa, a resposta do seu servidor e o horário.

Começar

Essenciais

Webhooks

Receitas

As sete famílias

`details`

Catálogo de códigos

Tratando na prática

Veja também

Repetir com segurança

Limites de requisição

​As sete famílias

​details

​Catálogo de códigos

​Tratando na prática

​Veja também

Repetir com segurança

Limites de requisição

As sete famílias

`details`

Catálogo de códigos

Tratando na prática

Veja também