Catálogo de Códigos de Erro

Este catálogo lista os valores de error.code que a API pode retornar, agrupados por status HTTP e por recurso. Para a estrutura do objeto de erro (envelope), veja Tratamento de Erros.

Trate erros pelo error.code, não pela message. O code é o identificador estável e legível por máquina (faz parte do contrato); a message é texto e pode mudar. Sempre presente na resposta.

Status HTTP

A API usa códigos de status HTTP padrão. O error.statusCode/error.category derivam do status:

Em erros que admitem nova tentativa (ex.: 429), a resposta pode incluir error.retryAfterMinutes indicando quanto esperar antes de repetir. Respeite esse valor no seu backoff.

Códigos comuns (cross-cutting)

Erros de validação de campos trazem detalhes por campo em error.params:

{
  "error": {
    "code": "invalidParameters",
    "statusCode": 400,
    "category": "validation",
    "message": "Validation errors occurred.",
    "params": [{ "amount": "amount must be a positive integer" }]
  }
}

Por recurso

Transactions

Subscriptions

/v1/subscriptions é Stripe-strict: a precificação vem das variantes; campos manuais são rejeitados.

Customers

Cards

Wallets

Withdrawals

Finance (Balance)

Products & Variants

Coupons

Addresses

Webhooks

Domains

Exports

Como tratar erros (recomendado)

const res = await fetch(url, { headers: { SelectKey: process.env.SELECTWIN_API_KEY } });
if (!res.ok) {
  const { error } = await res.json();
  switch (error.code) {                       // ← key no code, nunca na message
    case 'customerNotFound':
      return handleMissingCustomer();
    case 'balanceIsInsufficient':
      return promptTopUp();
    default:
      if (error.statusCode === 429) return retryWithBackoff();   // rate limit
      if (error.statusCode >= 500)  return retryWithBackoff();   // transitório
      throw new Error(`${error.code}: ${error.message}`);
  }
}

Esta lista cobre os erros mais comuns voltados ao desenvolvedor para cada recurso público. Outros códigos específicos podem aparecer; trate sempre o default pelo error.statusCode/category.