Error Codes

Flux API returns standard HTTP status codes along with detailed error information. This reference documents all possible error responses.

Error Response Format

All error responses follow this format:

{
  "error": "ERROR_CODE",
  "message": "Human-readable error description",
  "code": 400,
  "details": {
    "field": "Additional context"
  }
}

HTTP Status Codes

400 Bad Request

The request was malformed or missing required parameters.

Error Code	Message	Cause
INVALID_REQUEST	Request body is invalid JSON	Malformed JSON in request body
MISSING_PARAMETER	Required parameter missing: {param}	Missing required query or body parameter
INVALID_PARAMETER	Invalid parameter value: {param}	Parameter value doesn't match expected format
INVALID_API_ID	API ID format is invalid	API ID doesn't match expected format
INVALID_ENDPOINT	Endpoint path is invalid	Endpoint path contains invalid characters

401 Unauthorized

Authentication failed or credentials are invalid.

Error Code	Message	Cause
MISSING_SIGNATURE	X-Signature header is required	Missing signature header in gateway request
MISSING_PAYMENT_TX	X-Payment-Tx header is required	Missing payment transaction header
INVALID_SIGNATURE	Signature verification failed	Signature doesn't match message or wallet
SIGNATURE_EXPIRED	Signature timestamp is too old	Signature older than 5 minutes
INVALID_WALLET	Wallet address could not be recovered	Signature doesn't correspond to valid wallet
NOT_AUTHENTICATED	Authentication required	Request requires wallet connection

402 Payment Required

Payment verification failed.

Error Code	Message	Cause
PAYMENT_NOT_FOUND	Transaction not found on chain	Transaction hash doesn't exist on blockchain
INSUFFICIENT_PAYMENT	Payment amount is less than required	Transaction amount is below API price
INVALID_PAYMENT_CHAIN	Payment on wrong blockchain	Transaction is on different chain than expected
PAYMENT_NOT_CONFIRMED	Transaction not yet confirmed	Transaction is pending, not yet mined
PAYMENT_REVERTED	Transaction was reverted	Transaction failed on-chain

403 Forbidden

The request is valid but not allowed.

Error Code	Message	Cause
FORBIDDEN	You don't have permission for this action	User doesn't own the resource
API_DISABLED	This API is currently disabled	Provider has disabled the API
RATE_LIMIT_EXCEEDED	Rate limit exceeded	Too many requests in short time
PROVIDER_BLOCKED	This provider is blocked	Provider account has been suspended

404 Not Found

The requested resource doesn't exist.

Error Code	Message	Cause
API_NOT_FOUND	API not found: {apiId}	API ID doesn't exist
ENDPOINT_NOT_FOUND	Endpoint not found	Target API endpoint doesn't exist
CALL_NOT_FOUND	Call history not found	Call ID doesn't exist

409 Conflict

The request conflicts with existing data.

Error Code	Message	Cause
API_ALREADY_EXISTS	API with this name already exists	Duplicate API name for provider
DUPLICATE_ENDPOINT	Endpoint already registered	Endpoint URL already in use

422 Unprocessable Entity

The request is valid but cannot be processed.

Error Code	Message	Cause
INVALID_OPENAPI	OpenAPI specification is invalid	OpenAPI spec doesn't conform to standard
INVALID_PRICE	Price must be greater than 0	Price is zero or negative
INVALID_CURRENCY	Currency not supported	Currency is not ETH or USDC
ENDPOINT_UNREACHABLE	Target endpoint is not reachable	Cannot connect to target API

429 Too Many Requests

Rate limit has been exceeded.

Error Code	Message	Cause
RATE_LIMIT_EXCEEDED	Rate limit exceeded. Retry after {seconds} seconds	Too many requests in time window
QUOTA_EXCEEDED	Monthly quota exceeded	Monthly request limit reached

500 Internal Server Error

An unexpected server error occurred.

Error Code	Message	Cause
INTERNAL_ERROR	An unexpected error occurred	Server-side error
DATABASE_ERROR	Database operation failed	Database connectivity issue
BLOCKCHAIN_ERROR	Blockchain operation failed	Issue connecting to blockchain
GATEWAY_ERROR	Failed to proxy request to target API	Error forwarding request to target

502 Bad Gateway

The gateway received an invalid response from the target API.

Error Code	Message	Cause
INVALID_GATEWAY_RESPONSE	Target API returned invalid response	Target API response is malformed
GATEWAY_TIMEOUT	Request to target API timed out	Target API didn't respond in time

503 Service Unavailable

The service is temporarily unavailable.

Error Code	Message	Cause
SERVICE_UNAVAILABLE	Service is temporarily unavailable	Server maintenance or overload
BLOCKCHAIN_UNAVAILABLE	Blockchain network is unavailable	Cannot reach blockchain network

Common Error Scenarios

Scenario: Making a Gateway Request

Problem: Getting 402 Payment Required

Checklist:

1. Verify transaction hash is correct and mined

2. Confirm payment amount meets API price

3. Check transaction is on correct blockchain

4. Ensure signature is fresh (within 5 minutes)

Scenario: Creating an API

Problem: Getting 422 Unprocessable Entity

Checklist:

1. Validate OpenAPI specification format

2. Ensure price is greater than 0

3. Verify endpoint URL is reachable

4. Check currency is ETH or USDC

Scenario: Authentication Failure

Problem: Getting 401 Unauthorized

Checklist:

1. Verify X-Signature header is present

2. Confirm X-Payment-Tx header is present

3. Check signature was generated correctly

4. Ensure timestamp is recent

Retry Strategy

For transient errors (5xx, 429), implement exponential backoff:

async function callWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.code >= 500 || error.code === 429) {
        const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
}

Support

For issues not covered here:

• Email: [e-mail]

• Check the GitHub issues