Errors

Toda respuesta de error es un cuerpo JSON con forma ProblemDetails con una string code estable — construye tu lógica de recuperación sobre code, no solo sobre el estado HTTP (varios errores distintos comparten el mismo estado). Esta página cubre los errores que la mayoría de los integradores realmente necesita manejar; no es exhaustiva de todo mensaje de validación posible.

Forma general

Estado HTTP	Significado general	Qué hacer
400	Falla de validación estructural/de tipo (solicitud malformada).	Corrige la forma de la solicitud; nunca reintentes sin cambiar nada.
401	Credencial ausente o inválida (X-Api-Key o Authorization: Bearer) — ver Autenticación.	Revisa cuál de los 3 principals necesita la ruta; nunca reintentes con la misma credencial.
403	La credencial es válida, pero no está autorizada para esa acción/recurso específico (ej.: acceso cross-Organization, o una ruta que exige Member JWT y recibió una API Key).	Revisa el alcance/permisos; nunca reintentes sin cambiar nada.
404	El recurso no existe, o no pertenece a la Organization de quien llama (ambas cosas son deliberadamente indistinguibles, para no filtrar existencia entre tenants).	Confirma el ID y que pertenece a tu Organization.
409	Un conflicto con estado ya existente — normalmente una regla "el primer registro gana" o una idempotency key reutilizada con un payload distinto.	Ver los códigos específicos abajo; generalmente significa "ya hecho", no "reintenta".
422	La solicitud está bien formada pero viola una regla de negocio (saldo insuficiente, modo no soportado, etc.).	Ver los códigos específicos abajo; corrige la condición subyacente, luego reintenta.

Conflictos de idempotencia

Código	Estado	Significado	Qué hacer
IDEMPOTENCY_KEY_CONFLICT	409	La Idempotency-Key (o campo del cuerpo, según la ruta) ya se usó con un payload distinto. Un replay real del mismo payload con la misma key devuelve el resultado original en vez de dar error.	Nunca generes una key nueva y reintentes sin pensar — si la solicitud original efectivamente tuvo éxito, reintentar con una key nueva la ejecuta por duplicado. Usa una key estable y determinística por intención real (ver Idempotency).
PAYOUT_BATCH_IDEMPOTENCY_KEY_CONFLICT	409	Misma regla, específica de CreatePayoutBatch.	Igual que arriba.

Network Execution

Código	Estado	Significado	Qué hacer
NETWORK_EXECUTION_FEE_INSUFFICIENT_BALANCE	422	La NetworkCostPayerAccount no tiene saldo suficiente para cubrir el costo de red cobrado. Las extensions del cuerpo de la respuesta incluyen payerAccountId, availableBalance, requiredAmount, deficit, billingAsset y remediation: "DEPOSIT_REQUIRED" — suficiente para resolverlo programáticamente, sin analizar el texto del mensaje.	Financia la Account (un Deposit normal) con al menos deficit más de billingAsset, luego reintenta — ver Network Execution § Primer financiamiento.
CUSTOMER_NETWORK_RESOURCE_INSUFFICIENT	422	En modo CUSTOMER_RESOURCES, tu ExecutionSource registrado no tiene capacidad de recurso on-chain declarada suficiente. Falla cerrado — sin fallback silencioso a ISHTARAN_RESOURCES, a menos que hayas optado por allowFallbackToIshtaranResources.	Aumenta tus recursos on-chain y resincroniza vía executionSources.syncResourceStake(...), o opta explícitamente por el fallback.
CUSTOMER_RESOURCE_STAKE_INVALID	400	Los valores pasados a syncResourceStake son estructuralmente inválidos (ej.: negativos).	Corrige la solicitud; nunca reintentes sin cambiar nada.
EXECUTION_SOURCE_ALREADY_REGISTERED	409	El primer registro gana — ya existe un ExecutionSource para ese par Wallet/AssetNetwork.	Busca el registro existente en vez de registrar de nuevo.
NETWORK_COST_PAYER_ACCOUNT_ALREADY_REGISTERED	409	El primer registro gana — ya existe una NetworkCostPayerAccount para ese par Organization/AssetNetwork.	Busca el registro existente en vez de registrar de nuevo.
EXECUTION_DESTINATION_ALREADY_REGISTERED	409	El primer registro gana — ya existe un ExecutionDestination para ese par Account/AssetNetwork.	Busca el registro existente en vez de registrar de nuevo.

Payout

Código	Estado	Significado	Qué hacer
PAYOUT_POLICY_MODE_NOT_SUPPORTED	422	Un intento de configurar PayoutPolicy como THRESHOLD o SCHEDULED — solo IMMEDIATE y MANUAL están soportados hoy (ver Payout en el CORE_API.md de cada SDK).	Usa IMMEDIATE o MANUAL; no construyas contra las otras dos como capabilities disponibles.
PAYOUT_BATCH_TRIGGER_NOT_SUPPORTED	422	La ruta pública CreatePayoutBatch solo crea lotes con trigger MANUAL — no existe un campo trigger en la solicitud pública.	Llama a CreatePayoutBatch sin ningún campo trigger; la automatización THRESHOLD/SCHEDULED no es alcanzable por esta ruta pública.

Validación

Código	Estado	Significado	Qué hacer
VALIDATION_ERROR	400	Falló la validación estructural de la solicitud (campo ausente/malformado). La respuesta incluye los errores específicos por campo.	Corrige la forma de la solicitud según el detalle devuelto; nunca reintentes sin cambiar nada.

Self-Custody

Ver Self-Custody § Errores para SIGNED_TRANSACTION_MISMATCH — una firma cuyo hash canónico recalculado no coincide se rechaza de inmediato, y la leg nunca se transmite.