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 envelope:
1{2 "error": {3 "type": "invalid_request",4 "code": "pair_not_supported",5 "message": "The trading pair DOGE/SHIB is not supported.",6 "param": "pair",7 "doc_url": "https://tetrafi.io/docs/integration/errors#pair_not_supported"8 }9}code is machine-readable and stable - switch on it. message is human-readable and may evolve. doc_url deep-links to the anchor on this page.
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.