Erros

A API retorna erros em JSON com o campo error. Esta página explica o formato, categoriza os códigos por origem (auth, payload, gateway, etc.) e mostra como tratar cada classe.

Hierarquia geral

Antes de descer nas tabelas, internalize o que cada faixa de HTTP significa na Allya:

401, 404 e a maioria dos 409 não retentar: vão falhar igual. 429, 5xx (exceto 501) retentar com backoff.

Formato

{
  "error": "invalid_input",
  "issues": [
    {
      "path": ["customer", "email"],
      "message": "Invalid email"
    }
  ]
}

• error: código curto em snake_case, estável. Use em switch no seu código.
• message: texto livre opcional, não estável. Para logs e UI, não para lógica.
• issues[]: quando aplicável (invalid_input), aponta cada campo problemático com path (caminho do objeto).
• Outros campos por código: provider em erros de gateway, method em erros de roteamento, action em not_implemented.

Exemplo real com múltiplos issues:

{
  "error": "invalid_input",
  "issues": [
    {
      "path": ["amount"],
      "message": "Expected number, received string"
    },
    {
      "path": ["customer", "document"],
      "message": "CPF/CNPJ deve ter 11 ou 14 dígitos"
    }
  ]
}

Erros de autenticação

Erros de payload

Erros de leitura

Erros de ação em pagamento

Erros de assinatura

Específicos de POST /v1/subscriptions e POST /v1/subscriptions/:id/cancel. As demais classes (auth, payload, roteamento, billing, gateway) também se aplicam.

Erros de roteamento

Erros de limite

Erros de billing da plataforma

Diferente dos demais, estes erros não falam do pagamento em si, e sim do estado da sua assinatura da Allya (billing da organização). Aparecem em POST /v1/payments e POST /v1/subscriptions quando a plataforma bloqueia novas cobranças. Não retentar antes de regularizar.

Erros de gateway

Erros inesperados

Tratamento recomendado

const response = await fetch("https://payments-api.allyasolutions.com/v1/payments", options);

if (!response.ok) {
  const body = await response.json().catch(() => null);

  if (response.status === 401) {
    throw new Error("Verifique a API key");
  }

  if (response.status === 409) {
    throw new Error(`Configuração incompleta: ${body?.error}`);
  }

  throw new Error(body?.error ?? "Erro inesperado");
}

Veja também

• Autenticação: checklist específico de 401.
• Rate limiting: backoff para 429.
• Idempotência: retentar 5xx com segurança usando externalId.
• Troubleshooting: cenários comuns de erro com passo a passo.