Error Reference

​

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.

​

401 Unauthorized

Returned when authentication fails.

​

403 Forbidden

Returned when access is denied due to account status.

​

404 Not Found

Returned when the requested resource is not found.

​

409 Conflict

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

​

422 Unprocessable Entity

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

​

429 Too Many Requests

Returned when rate limits are exceeded.

​

500 Internal Server Error

Returned when an unexpected error occurs on the server.

​

502 Bad Gateway

Returned when a downstream service fails.

​

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 support@opper.ai or join our Discord.