Errors

Toda resposta de erro é um corpo JSON no formato ProblemDetails com uma string code estável — construa sua lógica de recuperação em cima do code, não só do status HTTP (vários erros distintos compartilham o mesmo status). Esta página cobre os erros que a maioria dos integradores realmente precisa tratar; não é exaustiva de toda mensagem de validação possível.

Formato geral

Status HTTP	Significado geral	O que fazer
400	Falha de validação estrutural/de tipo (requisição malformada).	Corrija o formato da requisição; nunca faça retry sem mudar nada.
401	Credencial ausente ou inválida (X-Api-Key ou Authorization: Bearer) — ver Autenticação.	Confira qual dos 3 principals a rota exige; nunca faça retry com a mesma credencial.
403	A credencial é válida, mas não autorizada para essa ação/recurso específico (ex.: acesso cross-Organization, ou uma rota que exige Member JWT e recebeu uma API Key).	Confira escopo/permissões; nunca faça retry sem mudar nada.
404	O recurso não existe, ou não pertence à Organization de quem chamou (as duas coisas são deliberadamente indistinguíveis, para não vazar existência entre tenants).	Confirme o ID e que ele pertence à sua Organization.
409	Um conflito com estado já existente — normalmente uma regra "primeiro registro vence" ou uma idempotency key reutilizada com um payload diferente.	Veja os códigos específicos abaixo; geralmente significa "já feito", não "tente de novo".
422	A requisição está bem formada mas viola uma regra de negócio (saldo insuficiente, modo não suportado, etc.).	Veja os códigos específicos abaixo; corrija a condição subjacente, depois tente de novo.

Conflitos de idempotência

Código	Status	Significado	O que fazer
IDEMPOTENCY_KEY_CONFLICT	409	A Idempotency-Key (ou campo do corpo, dependendo da rota) já foi usada com um payload diferente. Um replay real do mesmo payload com a mesma key retorna o resultado original em vez de dar erro.	Nunca gere uma key nova e tente de novo sem pensar — se a requisição original realmente teve sucesso, tentar de novo com uma key nova executa em dobro. Use uma key estável e determinística por intenção real (ver Idempotency).
PAYOUT_BATCH_IDEMPOTENCY_KEY_CONFLICT	409	Mesma regra, específica de CreatePayoutBatch.	Igual acima.

Network Execution

Código	Status	Significado	O que fazer
NETWORK_EXECUTION_FEE_INSUFFICIENT_BALANCE	422	A NetworkCostPayerAccount não tem saldo suficiente para cobrir o custo de rede cobrado. As extensions do corpo da resposta incluem payerAccountId, availableBalance, requiredAmount, deficit, billingAsset e remediation: "DEPOSIT_REQUIRED" — suficiente para resolver programaticamente, sem parsear o texto da mensagem.	Financie a Account (um Deposit normal) em pelo menos deficit a mais de billingAsset, depois tente de novo — ver Network Execution § Primeiro financiamento.
CUSTOMER_NETWORK_RESOURCE_INSUFFICIENT	422	No modo CUSTOMER_RESOURCES, seu ExecutionSource registrado não tem capacidade de recurso on-chain declarada suficiente. Falha fechada — sem fallback silencioso para ISHTARAN_RESOURCES, a menos que você tenha optado por allowFallbackToIshtaranResources.	Aumente seus recursos on-chain e re-sincronize via executionSources.syncResourceStake(...), ou opte explicitamente pelo fallback.
CUSTOMER_RESOURCE_STAKE_INVALID	400	Os valores passados para syncResourceStake são estruturalmente inválidos (ex.: negativos).	Corrija a requisição; nunca tente de novo sem mudar nada.
EXECUTION_SOURCE_ALREADY_REGISTERED	409	Primeiro registro vence — já existe um ExecutionSource para esse par Wallet/AssetNetwork.	Busque o registro existente em vez de registrar de novo.
NETWORK_COST_PAYER_ACCOUNT_ALREADY_REGISTERED	409	Primeiro registro vence — já existe uma NetworkCostPayerAccount para esse par Organization/AssetNetwork.	Busque o registro existente em vez de registrar de novo.
EXECUTION_DESTINATION_ALREADY_REGISTERED	409	Primeiro registro vence — já existe um ExecutionDestination para esse par Account/AssetNetwork.	Busque o registro existente em vez de registrar de novo.

Payout

Código	Status	Significado	O que fazer
PAYOUT_POLICY_MODE_NOT_SUPPORTED	422	Uma tentativa de configurar PayoutPolicy como THRESHOLD ou SCHEDULED — só IMMEDIATE e MANUAL são suportados hoje (ver Payout no CORE_API.md de cada SDK).	Use IMMEDIATE ou MANUAL; não construa contra as outras duas como capabilities disponíveis.
PAYOUT_BATCH_TRIGGER_NOT_SUPPORTED	422	A rota pública CreatePayoutBatch só cria lotes com gatilho MANUAL — não existe campo trigger na requisição pública.	Chame CreatePayoutBatch sem nenhum campo trigger; automação THRESHOLD/SCHEDULED não é alcançável por essa rota pública.

Validação

Código	Status	Significado	O que fazer
VALIDATION_ERROR	400	Falha na validação estrutural da requisição (campo ausente/malformado). A resposta inclui os erros específicos por campo.	Corrija o formato da requisição conforme o detalhe retornado; nunca tente de novo sem mudar nada.

Self-Custody

Veja Self-Custody § Erros para SIGNED_TRANSACTION_MISMATCH — uma assinatura cujo hash canônico recalculado não bate é rejeitada de cara, e a leg nunca é transmitida.