Error Reference

This document provides a comprehensive overview of all error responses in the Opper API v2.

Error Response Format

All API errors are returned with a consistent format:

{
  "type": "ErrorType",
  "message": "Error message",
  "detail": "Detailed information about the error"
}

HTTP Status Codes

400 Bad Request

Returned when the request is malformed or invalid.

Error Type	Error Message	Description
BadRequestError	The request is invalid	Generic validation or request error
StructuredGenerationError	The structured generation failed	Model couldn’t generate valid structured output
ContentPolicyViolationError	Content policy violation error	Content violates provider policies
ContextWindowExceededError	Context window exceeded error	Request exceeds model’s context window

401 Unauthorized

Returned when authentication fails.

Error Type	Error Message	Description
UnauthorizedError	The request is unauthorized	Authentication failed
UnauthorizedError	The request is unauthorized	No authentication provided

403 Forbidden

Returned when access is denied due to account status.

Error Type	Error Message	Description
HTTPException	Account suspended	User account is suspended

404 Not Found

Returned when the requested resource is not found.

Error Type	Error Message	Description
NotFoundError	The resource was not found	Function not found
NotFoundError	The resource was not found	Function revision not found
NotFoundError	The resource was not found	Dataset not found
NotFoundError	The resource was not found	Dataset entry not found
NotFoundError	The resource was not found	Custom model not found
NotFoundError	The resource was not found	Span not found
NotFoundError	The resource was not found	Parent span not found
NotFoundError	The resource was not found	Metric not found
NotFoundError	The resource was not found	Trace not found
NotFoundError	The resource was not found	Knowledge base not found
NotFoundError	The resource was not found	Index not found
NotFoundError	The resource was not found	File not found

409 Conflict

Returned when the request conflicts with the current state of the server.

Error Type	Error Message	Description
ConflictError	The resource already exists	Function name conflict
ConflictError	The resource already exists	Function name exists during update
ConflictError	The resource already exists	Custom model name conflict
ConflictError	The resource already exists	Custom model identifier conflict
ConflictError	The resource already exists	Index name conflict
ConflictError	The resource already exists	Metric already exists

422 Unprocessable Entity

Returned when the request is well-formed but contains semantic errors.

Error Type	Error Message	Description
RequestValidationError	Request validation error	Pydantic validation errors

429 Too Many Requests

Returned when rate limits are exceeded.

Error Type	Error Message	Description
RateLimitError	Rate limit exceeded	Rate limit from LLM provider

500 Internal Server Error

Returned when an unexpected error occurs on the server.

Error Type	Error Message	Description
InternalServerError	Internal server error	Unexpected server error

502 Bad Gateway

Returned when a downstream service fails.

Error Type	Error Message	Description
LLMProviderError	LLM provider error	LLM provider error
LLMProviderError	LLM provider error	Connection error to LLM provider

Common Error Scenarios and Solutions

Authentication Issues

If you receive 401 errors:

• Verify your API key is correct and active
• Ensure you’re including the API key in the request header as a bearer token: Authorization: Bearer YOUR_API_KEY
• Check that your API key hasn’t been revoked or suspended

Account Suspension

If you receive 403 errors:

• Contact support if your account has been suspended
• Review terms of service compliance

Resource Not Found

If you receive 404 errors:

• Check that the UUID or identifier you’re using is correct
• Verify that the resource belongs to your organization and project
• Ensure the resource hasn’t been deleted

Validation Errors

If you receive 400 or 422 errors:

• Check your request payload against the API specifications
• Ensure all required fields are provided and have the correct data types
• Validate your JSON schemas against the JSON Schema specification
• Review field patterns and constraints (e.g., function names must match the pattern ^[a-zA-Z0-9_.-]+$)

Conflict Errors

If you receive 409 errors:

• Use unique names when creating resources
• Check if a resource already exists before creating it
• Consider updating existing resources instead of creating new ones

Structured Generation Errors

If you receive StructuredGenerationError:

• Simplify your output schema
• Make your instructions more clear and specific
• Provide examples to help the model understand the expected output format
• Ensure your schema is valid JSON Schema

LLM Provider Errors

If you receive 502 errors with LLMProviderError:

• Implement retry logic with exponential backoff
• Check if there are known issues with the downstream LLM provider
• Verify your model selection is correct and available

Rate Limiting

If you receive 429 errors:

• Add fallback models to your requests
• Implement exponential backoff in your client
• Reduce request frequency

Content Policy Violations

If you receive ContentPolicyViolationError:

• Review your input content for policy violations
• Modify your prompts to comply with provider content policies
• Use different phrasing or approach for sensitive content

Context Window Exceeded

If you receive ContextWindowExceededError:

• Reduce the size of your input
• Use a model with a larger context window
• Implement chunking strategies for large inputs

Error Response Examples

Bad Request Example

{
  "type": "BadRequestError",
  "message": "The request is invalid",
  "detail": "Invalid model: 'gpt-3.5', did you mean 'openai/gpt-3.5-turbo'? For a complete list of available models, see https://docs.opper.ai/capabilities/models"
}

Not Found Example

{
  "type": "NotFoundError",
  "message": "The resource was not found",
  "detail": "Function abc123-def456-789012 not found"
}

Conflict Example

{
  "type": "ConflictError",
  "message": "The resource already exists",
  "detail": "Function my-function already exists as id 123e4567-e89b-12d3-a456-426614174000"
}

Structured Generation Error Example

{
  "type": "StructuredGenerationError",
  "message": "The structured generation failed",
  "detail": "The structured generation failed, could not generate response matching the schema"
}

Validation Error Example

{
  "type": "RequestValidationError",
  "message": "Request validation error",
  "detail": {
    "type": "missing",
    "loc": ["body", "instructions"],
    "msg": "Field required",
    "input": {"name": "test-function"}
  }
}

Further Assistance

If you encounter errors not documented here or need further assistance, please contact support at [e-mail] or join our Discord.