Error Reference

​

Error Response Format

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

​

HTTP Status Codes

​

400 Bad Request

​

401 Unauthorized

​

403 Forbidden

​

404 Not Found

​

409 Conflict

​

422 Unprocessable Entity

​

429 Too Many Requests

​

500 Internal Server Error

​

502 Bad Gateway

​

Common Error Scenarios and Solutions

​

Authentication Issues

• 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

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

​

Resource Not Found

• 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

• 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

• 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

• 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

• 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

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

​

Content Policy Violations

• 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

• 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