API Errors

The DuckyDux API follows RFC 9457 (Problem Details for HTTP APIs) to provide structured, machine-readable error responses. All error responses include standardized fields for consistent error handling across your application.

Error Response Format

All errors return a JSON response with the following structure:


{
  "type": "https://docs.duckydux.com/developer-api/errors#validation-error",
  "title": "Validation error",
  "status": 422,
  "detail": "Invalid token address format: must be a valid Ethereum address",
  "request_id": "e211b4168fba68153824bd1ae27ea353"
}

Response Fields

type: A URI reference identifying the error type (used for programmatic handling)
title: A short, human-readable summary of the error type
status: The HTTP status code
detail: A human-readable explanation specific to this occurrence
request_id: Unique request identifier for debugging (optional)

Always use the type field for programmatic error handling, not the detail field which may vary.

Client Errors - 4xx

`invalid-argument`

Status Code: 400 Bad Request

Description: The request contains structurally or semantically invalid parameters. This indicates malformed input data that fails basic validation before reaching business logic.

Common Causes:

Invalid data types — for example, string where number expected
Malformed Ethereum addresses
Invalid enum values
Missing required parameters
Parameters outside valid ranges

Example Response:


{
  "type": "https://docs.duckydux.com/developer-api/errors#invalid-argument",
  "title": "Invalid argument",
  "status": 400,
  "detail": "Parameter 'slippage_percent' must be between 0.0 and 100.0"
}

Resolution:

Validate input parameters before making API calls
Check parameter types match the API specification
Verify Ethereum addresses use correct checksum format
Review the OpenAPI Specification for correct parameter specifications

`validation-error`

Status Code: 422 Unprocessable Entity

Description: The request is well-formed but fails schema validation rules. This occurs when input data is structurally correct but violates data validation constraints.

Common Causes:

Field validation failures (min/max length, pattern matching)
Data constraint violations
Invalid combinations of parameters
Duplicate values in arrays that require uniqueness
Empty arrays where at least one item is required

Example Response:


{
  "type": "https://docs.duckydux.com/developer-api/errors#validation-error",
  "title": "Validation error",
  "status": 422,
  "detail": "Field 'sources' must contain at least 1 item"
}

Resolution:

Review validation error details in the detail field
Ensure all required fields are present and valid
Check array lengths meet minimum/maximum requirements
Verify no duplicate entries in fields requiring uniqueness
Consult the API documentation for field constraints

`unprocessable-request`

Status Code: 422 Unprocessable Entity

Description: The request is syntactically correct and passes validation, but cannot be processed due to domain-level constraints or business logic rules. This indicates a semantic error that prevents execution.

Common Causes:

Insufficient liquidity for the requested swap amount
No viable swap route found between token pairs
Slippage tolerance too restrictive for market conditions
Token pair not supported or inactive
Swap amount below minimum threshold
Requested operation violates business rules

Example Response:


{
  "type": "https://docs.duckydux.com/developer-api/errors#unprocessable-request",
  "title": "Unprocessable request",
  "status": 422,
  "detail": "No swap route found for the specified token pair with available liquidity"
}

Resolution:

Reduce swap amount if insufficient liquidity
Increase slippage tolerance for volatile markets
Verify token pair is actively traded and has liquidity
Check that token addresses are correct and indexed
Consider splitting large orders into smaller chunks

`not-found`

Status Code: 404 Not Found

Description: The requested resource does not exist. This typically occurs when querying for a specific entity by ID or address that cannot be found in the system.

Common Causes:

Invalid or non-existent pool address
Bundle ID not found or expired
Token not indexed in the system
Incorrect URL path or endpoint
Resource was deleted or never existed

Example Response:


{
  "type": "https://docs.duckydux.com/developer-api/errors#not-found",
  "title": "Not found",
  "status": 404,
  "detail": "Pool with address 0x1234...5678 not found"
}

Resolution:

Verify the resource ID or address is correct
Check for typos in addresses or identifiers
Use list/search endpoints to discover valid resources
Ensure the resource has been indexed (may take time for new resources)

`rate-limited`

Status Code: 429 Too Many Requests

Description: The client has exceeded their request quota for the specified time window. Rate limits protect the API from abuse and ensure fair resource allocation across all users.

Response Headers:

RateLimit-Limit: Allowed limit in the current timeframe
RateLimit-Remaining: Number of available requests remaining
RateLimit-Reset: Time remaining (in seconds) until quota resets
Retry-After: Seconds to wait before retrying
X-RateLimit-Limit-Second: Maximum requests allowed per second
X-RateLimit-Limit-Minute: Maximum requests allowed per minute
X-RateLimit-Remaining-Second: Requests remaining in current second
X-RateLimit-Remaining-Minute: Requests remaining in current minute

Example Response:


{
  "message": "API rate limit exceeded"
}

Note: The API gateway returns this simple error message. Application-layer rate limits may return RFC 9457-compliant responses with additional context.

Resolution:

Check the Retry-After header to determine wait time
Use RateLimit-Remaining headers to track quota consumption
Implement exponential backoff retry logic
Reduce request frequency in your application
Cache responses to minimize redundant API calls
See Rate Limits Reference for limits per endpoint group
Contact support if you need higher rate limits

Ignoring rate limits may result in temporary IP blocking. Always implement proper rate limit handling.

Server Errors - 5xx

`operation-unavailable`

Status Code: 503 Service Unavailable

Description: A temporary service-side limitation prevents the operation from being completed. The service is currently unable to handle the request but may be available later.

Common Causes:

External service dependency failure (RPC provider, database)
Service temporarily overloaded or degraded
Scheduled maintenance window
Resource exhaustion (memory, connections)
Circuit breaker triggered for failing dependencies

Example Response:


{
  "type": "https://docs.duckydux.com/developer-api/errors#operation-unavailable",
  "title": "Operation unavailable",
  "status": 503,
  "detail": "Swap routing service temporarily unavailable"
}

Resolution:

Retry the request after a short delay (use exponential backoff)
Check the API status page for known issues
Implement fallback mechanisms or queue requests
Monitor retry attempts to avoid infinite loops
Contact support if the issue persists beyond 5 minutes

`timeout`

Status Code: 503 Service Unavailable

Description: The request exceeded the configured timeout threshold. This may indicate network issues, slow external services, or unusually complex operations.

Common Causes:

Network latency or connectivity problems
Complex swap route computation taking too long
Blockchain RPC provider delays or congestion
Service infrastructure overload
Large batch operations exceeding time limits

Example Response:


{
  "type": "https://docs.duckydux.com/developer-api/errors#timeout",
  "title": "Request timed out",
  "status": 503,
  "detail": "Request timed out after 30 seconds"
}

Resolution:

Retry the request (may succeed on subsequent attempts)
Reduce complexity of the operation if possible
Break large operations into smaller batches
Check your network connectivity and DNS resolution
Consider increasing client-side timeout values

Additional Resources

Error Handling Guide - Complete implementation patterns and scenarios
Rate Limits Reference - Rate limits per endpoint group
OpenAPI Specification - Full API reference documentation
RFC 9457 - Problem Details for HTTP APIs standard