Error codes
errors.intro
| Code | HTTP | Meaning | Recovery |
|---|---|---|---|
| AUTH_MISSING | 401 | No Authorization header was sent. | Add Authorization: Bearer <api_key>. |
| AUTH_INVALID | 401 | The API key is revoked, malformed, or scoped to a different environment. | Verify the key in dashboard.zyndpay.io/settings/api-keys. |
| PERMISSION_DENIED | 403 | The API key lacks the scope to perform this operation. | Create a new key with the required scope — scopes are immutable after creation. |
| NOT_FOUND | 404 | The resource does not exist or belongs to another merchant. | Double-check the id and environment (sandbox vs live are isolated). |
| VALIDATION_FAILED | 400 | Request body failed DTO validation. See details[] for per-field reasons. | Fix the highlighted fields and retry. No idempotent retry required. |
| IDEMPOTENCY_CONFLICT | 409 | An earlier request with the same Idempotency-Key produced a different body. | Use a fresh key — keys are bound to a specific payload hash. |
| RATE_LIMITED | 429 | Per-merchant rate limit exceeded (see issue #201). | Back off using the Retry-After header. Default 60s. |
| INSUFFICIENT_BALANCE | 422 | Merchant USDT balance is lower than the requested payout or withdrawal. | Top up via pay-ins or reduce the amount. |
| DESTINATION_NOT_WHITELISTED | 422 | Payout target address is not in the merchant whitelist. | Add the address in dashboard.zyndpay.io/settings/whitelist first. |
| COMPLIANCE_HOLD | 423 | Transaction flagged by AML/KYB and requires manual review. | Email [email protected] — do NOT retry, it will re-trigger the same review. |
| CHAIN_UNAVAILABLE | 503 | Upstream TRON node or Tatum is unreachable. Circuit breaker is open (#240). | Retry with exponential backoff. Status page reflects ongoing incidents. |
| WEBHOOK_SIGNATURE_INVALID | 401 | Returned by the sandbox echo endpoint when the signature does not match. | Sign raw bytes (not re-encoded JSON) with the secret you received at webhook creation. |
| INTERNAL_ERROR | 500 | Unexpected error — a Sentry trace has been recorded. | Include the requestId field when contacting support. |