Error handling

When making API calls to Respan, you may encounter errors from two sources:

1. Respan errors - Errors thrown by the Respan platform itself
2. Provider errors - Errors from the underlying LLM provider (e.g., OpenAI, Anthropic)

Respan Exceptions

When Respan encounters an error, it will throw a RespanException. The error response will include details about what went wrong.

Common Respan Error Responses

401 Unauthorized

1
{
2
  "detail": "Your API key is invalid or expired, please check your API key at https://platform.respan.ai/platform/api/api-keys"
3
}

400 Bad Request

1
{
2
  "detail": "Invalid request format"
3
}

422 Unprocessable Entity

1
{
2
  "detail": "Validation error",
3
  "errors": {
4
    "field_name": ["Error message"]
5
  }
6
}

429 Too Many Requests

1
{
2
  "detail": "Rate limit exceeded",
3
  "retry_after": 60
4
}

500 Internal Server Error

1
{
2
  "detail": "Internal server error",
3
  "error_code": "INTERNAL_ERROR"
4
}

Provider Exceptions

When an error originates from the underlying LLM provider (e.g., OpenAI, Anthropic), Respan will surface the provider’s error response directly. The exception type will match the provider’s exception (e.g., OpenAIException for OpenAI errors).

OpenAI Errors

When using OpenAI models, you may encounter OpenAIException. The error response will be in OpenAI’s format:

1
{
2
  "error": {
3
    "message": "Incorrect API key provided",
4
    "type": "invalid_request_error",
5
    "param": null,
6
    "code": "invalid_api_key"
7
  }
8
}

Anthropic Errors

When using Anthropic models, you may encounter AnthropicException:

1
{
2
  "error": {
3
    "type": "authentication_error",
4
    "message": "Invalid API key"
5
  }
6
}