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

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 de um template interno (não são definidos campo a campo). Cada error.code mapeia para um template, e o template define o trio statusCode / status / category:

`category`	Status	Template interno	Significado
`validation`	`400`	`badRequest`	Requisição malformada ou parâmetro inválido (veja `error.params`)
`authentication`	`401`	`unauthorized`	Credencial (`SelectKey` / login) ausente, inválida ou revogada
`payment`	`402`	`paymentRequired`	Pagamento recusado pelo emissor
`authorization`	`403`	`forbidden`	Autenticado, mas sem permissão / conta não ativa
`client`	`404`	`notFound`	Recurso não encontrado
`client`	`409`	`conflict`	Conflito (estado incompatível, duplicidade, idempotência)
`client`	`413`	`payloadTooLarge`	Corpo da requisição grande demais
`validation`	`422`	`unprocessable`	Entidade não processável (regra de negócio)
`rate_limit`	`429`	`tooManyRequests`	Limite de requisições excedido (veja API Limits)
`server`	`500`	`internalServerError`	Erro interno — tente novamente; se persistir, contate o suporte
`server`	`503`	`serviceUnavailable`	Indisponibilidade temporária de um serviço — repita com backoff

Observação: erros de validação de contrato são sempre 400 / validation (com error.params), nunca 422. O 422 é reservado para regras de negócio (entidade processável sintaticamente, mas rejeitada).

Em erros que admitem nova tentativa (ex.: 429), respeite o cabeçalho Retry-After da resposta no seu backoff.

Códigos comuns (cross-cutting)

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

`error.code`	HTTP	Quando ocorre
`invalidParameters`	400	Falha de validação de contrato (veja `error.params` para os campos)
`unauthorized`	401	`SelectKey`/token ausente, inválido ou revogado
`forbidden`	403	Autenticado, mas sem permissão para a operação
`payloadTooLarge`	413	Corpo da requisição excede o limite (envie arquivos via `/v1/assets`)
`tooManyRequests`	429	Rate limit atingido (veja API Limits)
`idempotencyInProgress`	409	Já há uma requisição em andamento com esta `X-Idempotency-Key`
`idempotencyMismatch`	409	Esta `X-Idempotency-Key` já foi usada com um payload diferente
`serverError`	500	Erro interno inesperado

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

`error.code`	HTTP	Mensagem
`transactionNotFound`	404	Transaction not found
`customerNotFound`	404	The customer for this transaction was not found
`cardNotFound`	404	The card for this transaction was not found
`addressNotFound`	404	The billing address was not found
`recipientNotFound`	404	A split recipient was not found
`disputeNotFound`	404	No dispute was found for this transaction
`cardCustomerMismatch`	422	The card does not belong to the customer
`transactionNotRefundable`	422	This transaction cannot be refunded in its current status
`refundAmountInvalid`	422	Refund amount inválido (≤ 0 ou acima do total já cobrado)
`refundInProgress`	409	A refund for this transaction is already in progress
`transactionNotCapturable`	422	This transaction is not awaiting capture
`captureAmountInvalid`	422	Capture amount inválido (≤ 0 ou acima do autorizado)
`transactionNotInDispute`	422	Defense evidence só pode ser enviada com a transação em disputa
`discountExceedsAmount`	422	O desconto deixa a cobrança abaixo do mínimo
`splitsExceedAmount`	422	A soma dos splits excede o valor cobrado
`splitsInvalid`	422	Um split resolve para valor inválido (zero ou negativo)
`installmentsExceedMax`	422	Parcelas acima do máximo oferecido no momento
`onBehalfOfInvalid`	422	onBehalfOf deve referenciar uma sub-conta sua (marketplace habilitado)
`sellerRatesMissing`	422	Conta sem taxa configurada — não pode transacionar

Erros de processamento do pagamento (motor de pagamentos, recurso payorch):

`error.code`	HTTP	Mensagem
`paymentDeclined`	402	The payment was declined by the issuer
`providerNotConfigured`	422	Nenhum provedor de pagamento configurado para o modo solicitado
`transactionNotFound`	404	Transaction not found at the provider
`providerUnavailable`	500	The payment provider is temporarily unavailable

Subscriptions

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

`error.code`	HTTP	Mensagem
`subscriptionNotFound`	404	Subscription not found
`customerNotFound`	404	The customer for this subscription was not found
`cardNotFound`	404	The card for this subscription was not found
`variantNotFound`	404	One or more product variants were not found
`cycleNotFound`	404	The billing cycle was not found for this subscription
`itemNotFound`	404	The line item was not found for this subscription
`splitNotFound`	404	The split was not found for this subscription
`splitRecipientNotFound`	404	The split recipient company was not found
`meteredItemNotFound`	404	Metered subscription item not found
`thresholdNotFound`	404	Billing threshold not found
`cardCustomerMismatch`	422	The card does not belong to the customer
`variantNotRecurring`	422	A variant is not priced for recurring billing
`subscriptionAlreadyCanceled`	422	This subscription is already canceled
`subscriptionNotModifiable`	422	A canceled subscription cannot be modified
`subscriptionNotPausable`	422	This subscription cannot be paused in its current status
`subscriptionNotResumable`	422	Only a paused subscription can be resumed
`noScheduledCycle`	422	There is no scheduled cycle to renew for this subscription
`subscriptionRequiresItem`	422	A subscription must keep at least one line item
`itemCurrencyMismatch`	422	The item currency must match the subscription currency
`duplicateSplitRecipient`	422	A split already exists for this recipient
`splitValueInvalid`	422	A percentage split value must be between 0 and 100
`usageOnNonMeteredItem`	422	Usage can only be reported on metered items
`usageActionUnsupported`	422	Usage action not supported (only 'increment')
`thresholdMisconfigured`	422	Billing threshold misconfigured
`thresholdAlreadyExists`	409	A billing threshold already exists for this item
`onBehalfOfInvalid`	422	onBehalfOf deve referenciar uma sub-conta sua (marketplace habilitado)

Customers

`error.code`	HTTP	Mensagem
`customerNotFound`	404	Customer not found
`invalidCustomerId`	404	The provided customer id is invalid
`customerEmailTaken`	409	A customer with this email already exists
`customerDocumentTaken`	409	A customer with this document already exists
`customerHasActiveSubscription`	409	Cliente com assinatura ativa não pode ser excluído (cancele a assinatura antes)

Cards

`error.code`	HTTP	Mensagem
`cardIdNotFound`	404	Card ID not found
`cardIdIsInvalid`	400	Card ID is invalid
`cardExpired`	400	Card expired
`invalidCardData`	422	Invalid card data
`cardBrandNotSupported`	422	Card brand not supported

Addresses

`error.code`	HTTP	Mensagem
`addressIdNotFound`	404	Address not found

Wallets (contas bancárias)

`error.code`	HTTP	Mensagem
`walletNotFound`	404	Wallet not found
`walletAlreadyExists`	409	A wallet with these account details already exists
`walletHasPendingWithdrawal`	409	Wallet com saque em andamento não pode ser excluída
`bankCodeNotSupported`	400	This bank code is not supported

Withdrawals (saques)

`error.code`	HTTP	Mensagem
`withdrawalNotFound`	404	Withdrawal not found
`withdrawalCreateNotEnabled`	400	Withdrawals are not enabled for this company
`withdrawalAmountLessThanMinimum`	400	The withdrawal amount is below the minimum

Auto-cashout (saque automático)

`error.code`	HTTP	Mensagem
`autoCashoutNotFound`	404	Auto-cashout config not found
`duplicateAutoCashoutForWallet`	400	An auto-cashout config already exists for this wallet
`percentageOverlapDetected`	400	A soma das porcentagens habilitadas não pode exceder 100%

Finance (Balance / Receivables)

`error.code`	HTTP	Mensagem
`balanceNotFound`	404	No balance found for this company yet
`balanceIsInsufficient`	422	Insufficient available balance for this withdrawal
`receivableNotFound`	404	Receivable not found

Products & Variants

`error.code`	HTTP	Mensagem
`productNotFound`	404	Product not found
`variantNotFound`	404	Variant not found
`invalidPricing`	422	Invalid advanced pricing configuration
`pricingTypeImmutable`	422	pricing.type is immutable
`pricingSchemaImmutable`	422	pricing.schema is immutable

Coupons

`error.code`	HTTP	Mensagem
`couponNotFound`	404	The coupon code was not found
`couponCodeConflict`	409	A coupon with this code already exists
`couponDisabled`	422	This coupon is no longer active
`couponNotYetActive`	422	This coupon is not active yet
`couponExpired`	422	This coupon has expired
`couponMinCartAmount`	422	Cart total abaixo do mínimo do cupom
`couponMaxCartAmount`	422	Cart total acima do máximo do cupom
`couponMinCartItems`	422	Menos itens do que o cupom exige
`couponMaxCartItems`	422	Mais itens do que o cupom permite
`couponNotApplicable`	422	This coupon does not apply to this cart
`couponUsageLimitReached`	422	This coupon has reached its usage limit
`couponCustomerLimitReached`	422	This coupon has already been used by this customer
`couponExceedsTotal`	422	The coupon discount exceeds the chargeable total

Checkout

`error.code`	HTTP	Mensagem
`checkoutSessionNotFound`	404	Checkout session not found
`checkoutSessionNotUpdatable`	409	A completed checkout session can no longer be updated
`checkoutSessionNotPayable`	409	This checkout session is not in a payable state
`variantIdIsInvalid`	422	One of the items references a product variant that does not exist
`onBehalfOfInvalid`	422	onBehalfOf deve referenciar uma sub-conta sua (marketplace habilitado)
`checkoutPaymentLinkNotFound`	404	Payment link not found
`checkoutPaymentLinkCreateFailed`	500	The payment link could not be created
`checkoutTemplateNotFound`	404	Checkout template not found
`checkoutTemplateIdIsInvalid`	422	The checkout template does not exist
`orderbumpNotFound`	404	Order bump not found
`reviewNotFound`	404	Checkout review not found
`shippingOptionNotFound`	404	Shipping option not found
`shippingOptionRequiresTemplateOrGlobal`	422	A shipping option must be global or bound to a checkout template
`checkoutMonitorNotFound`	404	Checkout monitor not found
`checkoutPixelNotFound`	404	Checkout tracking pixel not found
`upsellNotFound` / `upsellOfferNotFound`	404	Upsell offer not found
`upsellParentNotFound`	404	Parent transaction not found
`upsellParentNotApproved`	422	A transação pai precisa estar aprovada para cobrar um upsell
`upsellOfferExpired`	422	This upsell offer has expired
`upsellOfferNotEligible`	422	This upsell offer is not eligible for the parent purchase
`upsellAmountTooLow`	422	The upsell amount is below the minimum chargeable value

Webhooks

`error.code`	HTTP	Mensagem
`webhookEndpointNotFound`	404	Webhook endpoint not found
`webhookEventNotFound`	404	Webhook event not found
`webhookDispatchNotFound`	404	Webhook dispatch not found
`webhookUnknownResource`	422	Unknown event resource — cannot build payload
`webhookSigningDisabled`	422	This endpoint has signing disabled (no secret)

Domains

`error.code`	HTTP	Mensagem
`domainIdIsInvalid`	404	Domain ID is invalid (not found for this company)
`domainAlreadyExists`	409	Domain already exists
`domainLimitExceeded`	409	Domain limit exceeded
`domainUpdateFailed`	400	Domain update failed
`domainEdgeProvisionFailed`	422	Domain edge provisioning failed

Authentication & API Keys

`error.code`	HTTP	Mensagem
`invalidPassword`	401	Invalid email or password
`userDisabled`	403	This account is not active. Verify your email to continue
`mfaCodeRequired`	401	This account has MFA enabled — a verification code is required
`mfaChallengeInvalid`	401	The MFA challenge is invalid, expired, or already used
`mfaTokenInvalid`	401	The verification code is incorrect
`stepUpRequired`	401	This operation requires recent authentication. Please re-authenticate
`recoveryTokenInvalid`	401	The password reset token is invalid or has expired
`resourceNotAllowed`	403	This resource is not allowed for this client
`operationMethodNotAllowed`	403	This operation is not allowed for this client
`companyNotMember`	403	You are not a member of this company
`sessionNotFound`	404	Session not found
`passwordMismatch`	422	The passwords do not match
`invalidApiKeyId`	400	API key not found
`m2mTokenUnauthorized`	401	Invalid client credentials

`error.code`	HTTP	Mensagem
`userEmailExists`	400	An account with this email already exists
`userEmailConfirmationTokenInvalid`	400	The email confirmation token is invalid
`companyLimitReached`	422	Você atingiu o máximo de empresas para esta conta
`companiesNotActive`	422	Finalize suas empresas existentes (todas ativas) antes de criar outra
`companyCreateForbidden`	403	You do not have permission to create a company from this account
`signupNotProcessable`	500	Could not create the account

Exports

`error.code`	HTTP	Mensagem
`exportNotFound`	404	The export was not found
`exportNotCancelable`	422	This export can no longer be canceled
`exportTooLarge`	422	The export exceeds the maximum allowed row count

Assets (upload)

`error.code`	HTTP	Mensagem
`assetNotFound`	404	The asset was not found
`assetUploadIncomplete`	422	No uploaded object was found for this asset yet
`assetCompanyUnresolved`	422	Could not resolve the company for this upload
`storageNotConfigured`	503	Object storage is not configured (indisponibilidade temporária)

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}`);
  }
}

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.

Catálogo de Códigos de Erro

On this page