← API reference
Troubleshooting
Error catalogue
Trust the HTTP status and stable error code rather than parsing message text. Preserve each response's request_id for support. Never log API keys, webhook secrets or authorization headers.
| Code | HTTP | Meaning | Recovery |
|---|---|---|---|
| INVALID_REQUEST | 400 | Malformed JSON, invalid field, cursor, or amount precision. | Correct the request; use a new idempotency key if the logical operation changes. |
| UNAUTHORIZED | 401 | Missing/invalid API key, revoked key, or environment mismatch. | Verify the full key, prefix and selected environment. |
| FORBIDDEN | 403 | Required API scope or workspace permission is missing. | Ask a workspace owner to issue a least-privilege key with the required scope. |
| NOT_FOUND | 404 | Resource is missing or not visible to this partner/environment. | Verify the identifier and environment. |
| CONFLICT | 409 | Resource or lifecycle state conflicts with the request. | Retrieve the latest resource state before retrying. |
| INVALID_STATE | 400 | Requested operation is not valid for the current deal state. | Fetch the deal and use a supported transition. |
| IDEMPOTENCY_CONFLICT | 409 | The same key is currently being processed. | Retry later with the same key and exact same request. |
| IDEMPOTENCY_MISMATCH | 409 | Key reused with a different method, path or body. | Generate a new key for the new logical operation. |
| RATE_LIMITED | 429 | Shared partner/environment rate limit exceeded. | Respect Retry-After and X-RateLimit-* headers; use bounded backoff. |
| UNSUPPORTED_RAIL | 422 | This API release does not support fiat settlement. | Use supported crypto escrow assets: SOL, USDC, USDT, EURC, PYUSD, USDS, or FDUSD. |
| LINK_USER_REQUIRED | 403 | A partner external user is not linked to a TrustLayer user. | Complete the required user-linking flow. |
| PROVIDER_ERROR | 502 | An upstream provider failed. | Retry only when safe and reuse the same idempotency key for supported writes. |
| BLOCKCHAIN_ERROR | 502 | A blockchain operation failed or could not be confirmed. | Verify the underlying transaction before retrying. |
| CONFIGURATION_ERROR | 500 | Required server configuration is missing. | Contact TrustLayer support; never expose server secrets. |
| INTERNAL | 500 | Unexpected server failure. | Include request_id when contacting support; retry writes only with the same idempotency key. |
The OpenAPI contract at /api/v1/openapi is the authoritative versioned schema. Fiat settlement is not available through this Partner API release.