Error Code Registry#
Every machine-readable error code TetraFi emits, grouped by HTTP status. Codes are documented once here and referenced from the rest of the docs via the inline <ErrorCode> pill.
| Code | Status | Category | Description | |
|---|---|---|---|---|
| invalid_request | 400 | validation | Malformed request or missing required parameter. | |
| missing_field | 400 | validation | Required field absent from request body. | |
| pair_not_supported | 400 | validation | The pair isn't available on the requested corridor. | |
| amount_too_small | 400 | validation | Below the minimum trade size for your tier. | |
| amount_too_large | 400 | validation | Exceeds the maximum trade size for your tier. | |
| corridor_unavailable | 400 | validation | No solvers currently cover the requested corridor. | |
| unauthorized | 401 | auth | Invalid or missing API key. | |
| invalid_key | 401 | auth | API key is invalid, revoked, or from the wrong environment. | |
| authentication_error | 401 | auth | Invalid or expired API key. | |
| compliance_failed | 403 | compliance | Participant not compliant to trade on this corridor. | |
| compliance_error | 403 | compliance | Participant not compliant to trade. | |
| attestation_expired | 403 | compliance | Compliance attestation needs renewal. | |
| attestation_missing | 403 | compliance | No compliance attestation on record for this participant. | |
| not_found | 404 | settlement | Resource (RFQ, quote, order, settlement) not found. | |
| conflict | 409 | settlement | Duplicate request (idempotency-key violation). | |
| quote_expired | 409 | settlement | Quote window has passed - request a new quote. | |
| already_accepted | 409 | settlement | Quote has already been accepted by another party. | |
| rfq_expired | 409 | settlement | Quote window has passed - create a new RFQ. | |
| validation_error | 422 | validation | Field types are valid but business rules failed. | |
| rate_limited | 429 | server | Too many requests - honor Retry-After header. | |
| rate_limit_error | 429 | server | Too many requests - honor Retry-After header. | |
| api_error | 500 | server | Internal server error - retry with exponential backoff. | |
| maintenance | 503 | server | Scheduled maintenance - check status page. |
Canonical surface - the inline error tables in Authentication and REST API Reference remain authoritative for their local context; this page is the consolidated index for deep-linking. Each row above deep-links to a per-code detail page at /docs/integration/errors/<code>/.
Response shape#
All error responses follow a single flat envelope:
1{2 "error": "NOT_FOUND",3 "message": "Order ord_01HXYZSTUVWX not found.",4 "timestamp": 17453246115}error is machine-readable, stable, and emitted in UPPER_SNAKE_CASE - switch on it. message is human-readable and may evolve. timestamp is a Unix epoch seconds marker for log correlation.
Optional fields appear only on specific responses:
| Field | When it appears | Purpose |
|---|---|---|
retryAfterSecs | 429 rate-limit | Seconds to wait before retry (paired with Retry-After header) |
retryAfterMs | 429 trade-path | Millisecond-precision sibling of retryAfterSecs |
class | 429 trade-path | Rate-limit class that tripped ("quote" / "order" / "read") |
limitPerSecond | 429 trade-path | Tier-adjusted per-second cap |
lockoutDuration | 429 ACCOUNT_LOCKED | Lockout length in seconds |
unlocksAt | 429 ACCOUNT_LOCKED | ISO-8601 expiry timestamp |
The per-code sections below group codes by HTTP status for discoverability. Each code is slugged in lowercase for URL-safe deep-linking, but the wire value emitted by the API is UPPER_SNAKE_CASE (e.g., the slug #not_found documents the wire code NOT_FOUND).
400 - Invalid Request#
invalid_request#
Malformed request, missing required param, or type mismatch. Inspect the request body; do not retry unchanged.
missing_field#
A required field was absent from the request body. param in the error body names the missing field.
pair_not_supported#
The pair isn't available on the requested corridor.
amount_too_small#
Below the minimum trade size ($10,000 USD equivalent for most corridors).
amount_too_large#
Exceeds the maximum trade size for your tier.
corridor_unavailable#
No solvers currently cover the requested corridor. Poll corridors/availability or choose an alternative route.
401 - Authentication#
unauthorized#
Invalid or missing API key. Check the Authorization: Bearer tfk_live_... header is present.
invalid_key#
API key is invalid, revoked, or from the wrong environment. Sandbox keys (tfk_test_) fail on api.tetrafi.io; live keys (tfk_live_) fail on sandbox.tetrafi.io.
authentication_error#
Invalid or expired API key. Rotate via the dashboard; old key remains valid for 24 hours after rotation.
403 - Compliance#
compliance_failed#
Participant not compliant to trade on this corridor. Check attestation tier and corridor compliance requirements.
compliance_error#
Participant not compliant to trade. Generic compliance rejection; inspect the message for specifics.
attestation_expired#
Compliance attestation needs renewal. Run the KYC/KYB refresh flow with your compliance provider.
attestation_missing#
No compliance attestation on record for this participant. Ensure the X-TetraFi-Attestation header is attached to the request.
404 - Not Found#
not_found#
Resource (RFQ, quote, order, settlement) not found. The resource may have expired, been deleted, or never existed.
409 - Conflict#
conflict#
Duplicate request - idempotency-key was reused for a different payload.
quote_expired#
Quote window has passed. Request a new quote from the quotes endpoint.
already_accepted#
Quote has already been accepted by another party. Request a new quote.
rfq_expired#
The RFQ quote window has passed - create a new RFQ.
422 - Validation#
validation_error#
Field types are valid but a business rule failed. For example: deadline in the past, nonce reuse, or decimals mismatch.
429 - Rate Limiting#
rate_limited#
Too many requests - honor the Retry-After header. Use exponential backoff on top of the header-provided delay.
rate_limit_error#
Too many requests - honor the Retry-After header.
500+ - Server#
api_error#
Internal server error - retry with exponential backoff. If persistent, check status.tetrafi.io.
maintenance#
Scheduled maintenance - check the status page for the expected end time.