Error Handling

BlockRun uses standard HTTP status codes and returns detailed error information.

HTTP Status Codes

Error Response Format

{
  "error": "Error type",
  "message": "Detailed error message",
  "details": {}
}

Common Errors

400 - Invalid Request

{
  "error": "Invalid request body",
  "details": [
    {"path": ["model"], "message": "Required"}
  ]
}

Causes:

• Missing required fields (model, messages)
• Invalid model ID
• Malformed JSON

402 - Payment Required

{
  "error": "Payment Required",
  "message": "This endpoint requires x402 payment",
  "price": {
    "amount": "0.001000",
    "currency": "USD"
  }
}

402 - Payment Rejected

{
  "error": "Payment verification failed",
  "details": "Insufficient balance"
}

Causes:

• Insufficient USDC balance
• Invalid signature
• Expired payment authorization

500 - Server Error

{
  "error": "Internal server error"
}

Causes:

• Upstream provider error
• Temporary service issue

SDK Error Classes

Troubleshooting

"Payment verification failed"

1. Check your USDC balance on Base
2. Ensure your wallet is on the correct network
3. Verify your private key is correct

"Unknown model"

1. Check the model ID matches exactly (e.g., openai/gpt-5.5)
2. See available models for valid IDs

"Timeout"

1. Increase the timeout in client options
2. Try a faster model (e.g., gpt-5.5 or gpt-5.4-mini instead of o1)

"Network error"

1. Check your internet connection
2. Verify blockrun.ai/api is accessible

What's next?