Error Handling

Standard Error Format

All errors return structured responses with API version metadata:

{
  "error": {
    "type": "validation|authentication|payment|server",
    "code": "SPECIFIC_ERROR_CODE",
    "message": "Human-readable error description"
  },
  "apiVersion": "v1",
  "timestamp": "2024-01-15T10:30:00Z"
}

HTTP Status Codes

Code	Meaning	Context
200	OK	Request successful
201	Created	Resource created
400	Bad Request	Invalid parameters
401	Unauthorized	Authentication required
402	Payment Required	x402 payment needed
403	Forbidden	Access denied
404	Not Found	Resource not found
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error
502	Bad Gateway	Upstream timeout or size limit exceeded

Payment-Specific Errors

{
  "error": "Payment Required",
  "x402Version": 1,
  "accepts": ["application/x-payment"],
  "paymentRequired": {
    "amount": "0.01",
    "currency": "USDC",
    "network": "base-sepolia"
  }
}

Proxy Errors (502 Bad Gateway)

Request Timeout

Cause: Target URL took longer than 10 minutes (600 seconds) to respond.

What happens:

• Client receives 502 Bad Gateway

• Credits are consumed (payment was made)

• Metrics are captured for analytics

Solutions:

• Use async patterns for long operations

• Return job IDs immediately, poll for results later

• Optimize your API response time

• Consider webhooks for long-running tasks

Response Size Limit Exceeded

Cause: Target URL returned a response larger than 10MB (10,485,760 bytes).

What happens:

• Request blocked with 502 Bad Gateway

• Credits are consumed (payment was made)

• Warning logged with actual size and limit

Solutions:

• Use File PayGates for large content (no size limit)

• Implement pagination for large datasets

• Compress responses (gzip/brotli)

• Stream data instead of returning all at once

Example - File PayGate for large content:

# Instead of proxying large files, upload to Sigwei storage
curl -X POST https://402ify.com/api/v1/paygates \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -F "price=100000" \
  -F "resourceType=file" \
  -F "file=@large-dataset.csv"

# Users get presigned URLs - no proxy bandwidth costs