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.

#Status HTTP

A API usa códigos de status HTTP padrão. Cada error.code tem sempre o mesmo statusCode e a mesma category:

#Códigos comuns (cross-cutting)

Estes códigos vêm do kernel e podem aparecer em qualquer rota (recurso server, exceto onde indicado):

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

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

#Por recurso

#Transactions

Erros de processamento do pagamento (recurso payments):

#Marketplace

Sub-contas de uma plataforma (/v1/marketplace/* — guia). Recurso de conta: toda escrita com chave de sandbox responde 409 accountLevelReadOnlyInSandbox.

A plataforma agindo como a sub-conta (X-Selectwin-Account, guia) — recurso authentication:

#Subscriptions

/v1/subscriptions é Selectwin-strict: a precificação vem das variantes recorrentes; não há campo amount nem preço manual.

#Customers

#Cards

#Addresses

#Wallets (contas bancárias)

#Withdrawals (saques)

#Auto-cashout (saque automático)

#Finance (Balance / Receivables)

#Products & Variants

#Coupons

#Checkout

#Webhooks

#Domains

#Permissões da conta

Quando a conta tem uma lista de permissões (recursos e operações liberados), uma chave de API que tenta sair dela recebe:

#Exports

#Assets (upload)

#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();
    case 'paymentDeclined':
      return promptAnotherCard();
    default:
      if (error.statusCode === 429) return retryWithBackoff();   // rate limit
      if (error.statusCode >= 500)  return retryWithBackoff();   // transitório
      throw new Error(`${error.code}: ${error.message}`);
  }
}