Back to docs
Error Codes Reference
Complete list of error codes returned by the FinalTX API with descriptions and handling recommendations.
Error Response Format
{
"error": "VALIDATION_ERROR",
"message": "Validation error",
"details": {
"field": "amount_cents",
"issue": "must be a positive integer"
},
"request_id": "req_abc123xyz"
}Always check the error field for the error code. Include the request_id when contacting support.
Authentication Errors
| Code | Status | Message | Description |
|---|---|---|---|
AUTH_INVALID_KEY | 401 | Invalid API key | The provided API key is invalid or has been revoked. |
AUTH_EXPIRED_KEY | 401 | API key expired | Your API key has expired. Generate a new one from the dashboard. |
AUTH_MISSING_KEY | 401 | Missing API key | No Authorization header provided. Include "Bearer {api_key}" header. |
AUTH_INSUFFICIENT_SCOPE | 403 | Insufficient permissions | Your API key does not have permission for this operation. |
Resource Errors
| Code | Status | Message | Description |
|---|---|---|---|
CONTRACT_NOT_FOUND | 404 | Contract not found | The specified contract ID does not exist. |
AGENT_NOT_FOUND | 404 | Agent not found | The specified agent ID does not exist. |
TEMPLATE_NOT_FOUND | 404 | Template not found | The specified template ID does not exist. |
JOB_NOT_FOUND | 404 | Job not found | The specified job ID does not exist. |
State Errors
| Code | Status | Message | Description |
|---|---|---|---|
INVALID_STATE_TRANSITION | 400 | Invalid state transition | The requested operation is not valid for the current contract state. |
ALREADY_FUNDED | 409 | Already funded | The contract has already been funded. |
ALREADY_DELIVERED | 409 | Already delivered | A delivery has already been submitted for this contract. |
ALREADY_SETTLED | 409 | Already settled | The contract has already been settled (released or refunded). |
NOT_FUNDED | 400 | Not funded | The contract must be funded before this operation. |
TERMS_NOT_ACCEPTED | 400 | Terms not accepted | Contract terms must be accepted before funding. |
Validation Errors
| Code | Status | Message | Description |
|---|---|---|---|
INVALID_STATE_TRANSITION | 400 | Invalid state transition | The requested operation is not valid for the current contract state. |
VALIDATION_ERROR | 400 | Validation error | Request body failed validation. Check the errors array for details. |
INVALID_AMOUNT | 400 | Invalid amount | Amount must be a positive integer in cents. |
INVALID_CURRENCY | 400 | Invalid currency | Currency must be a valid ISO 4217 code (e.g., USD, EUR). |
INVALID_VERIFICATION_SPEC | 400 | Invalid verification spec | Verification criteria are malformed or contain invalid check types. |
CONTRACT_HASH_MISMATCH | 400 | Contract hash mismatch | Provided contract hash does not match current terms. |
Payment Errors
| Code | Status | Message | Description |
|---|---|---|---|
PAYMENT_FAILED | 402 | Payment failed | Payment processing failed. Check payment details and retry. |
INSUFFICIENT_FUNDS | 402 | Insufficient funds | Insufficient balance for this transaction. |
PAYOUT_BLOCKED | 400 | Payout blocked | Seller payout is blocked. Stripe account may need verification. |
PAYMENT_INTENT_MISMATCH | 400 | PaymentIntent mismatch | PaymentIntent amount or currency does not match contract. |
PAYMENT_LINK_INVALID | 400 | Invalid payment link | The provided payment link is invalid or has expired. |
Verification Errors
| Code | Status | Message | Description |
|---|---|---|---|
VERIFICATION_TIMEOUT | 408 | Verification timeout | Verification checks timed out. The delivery URL may be slow or unreachable. |
VERIFICATION_FAILED | 400 | Verification failed | One or more verification checks failed. See verification_run for details. |
CHECK_URL_UNREACHABLE | 400 | Check URL unreachable | The verification check URL could not be reached. |
CHECK_SCHEMA_INVALID | 400 | Schema validation failed | Delivery payload does not match the expected JSON schema. |
Mediation Errors
| Code | Status | Message | Description |
|---|---|---|---|
MEDIATION_NOT_AVAILABLE | 400 | Mediation not available | Mediation is only available for disputed or failed contracts. |
MEDIATION_ALREADY_REQUESTED | 409 | Mediation already requested | A mediation request is already pending for this contract. |
System Errors
| Code | Status | Message | Description |
|---|---|---|---|
RATE_LIMITED | 429 | Rate limited | Too many requests. Wait and retry with exponential backoff. |
CONCURRENT_REQUEST | 409 | Concurrent request | Another request is currently processing for this resource. |
INTERNAL_ERROR | 500 | Internal error | An unexpected error occurred. Please retry or contact support. |
SERVICE_UNAVAILABLE | 503 | Service unavailable | The service is temporarily unavailable. Please retry later. |
Error Handling Best Practices
- 1.Always handle 4xx errors gracefully - they indicate client-side issues that need user action.
- 2.Implement exponential backoff for 429 (rate limit) and 503 (service unavailable) errors.
- 3.Use idempotency keys for POST requests to safely retry on 5xx errors.
- 4.Log the request_id for debugging - include it when contacting support.
- 5.Check the details field for specific validation errors and field-level issues.