Error code reference
Authentication Issues
401 Unauthorized: check your API key format and permissions
Bad Request Data
400 + validation_error: verify required fields and data types
Rate Limiting
429 Too Many Requests: implement exponential backoff
Server Problems
5xx Errors: check our status page or retry your request
Error types
Jump to specific error types to find the cause and suggested action:- Authentication and authorization errors
- Request validation errors
- Rate limiting and quota errors
- Server and processing errors
- Error codes by service
Error response format
All API endpoints return errors in a consistent JSON format:Response structure
🔧 Core fields (always present)
🔧 Core fields (always present)
📋 Error message details
📋 Error message details
HTTP status codes
Writer APIs use standard HTTP status codes to indicate the nature of errors:Error codes by service
This section provides a comprehensive reference of all possible error codes organized by service and endpoint.Chat Completions API
Chat Completions API
Knowledge Graphs API
Knowledge Graphs API
Applications API
Applications API
Tools API
Tools API
Vision API
Vision API
Guardrails
Guardrails
Guardrail errors occur when content is blocked by configured safety controls. For more information, see Configure guardrails.How to Fix:
Content blocked by guardrail
Example guardrail error:
- Review the blocked entity type or violation reason in the error response
- Remove or mask sensitive content before retrying
- Check guardrail configuration if blocks are unexpected
- See Guardrails documentation for configuration options
Error categories
Authentication and authorization errors
401 Unauthorized
Example Response:
- Verify your API key is correct
- Ensure you’ve included the
Authorization: Bearer <your_api_key>header - Check that your API key hasn’t expired
- See API Keys documentation for more details
403 Forbidden
Example Response:
- Verify your API key has the required permissions
- Check if you’re using the correct API key type
- Contact support if permissions seem incorrect
Request validation errors
400 Bad Request
Example Response:
- Check required fields and data formats
- Validate parameter values against API documentation
- Ensure request body is valid JSON
- See specific endpoint documentation for required parameters
404 Not Found
Example Response:
- Verify the resource ID is correct
- Check if the resource has been deleted
- Ensure the endpoint URL is correct
Rate limiting and quota errors
429 Too Many Requests
Example Response:
- Implement exponential backoff
- Check your rate limits in the dashboard
- Consider upgrading your plan for higher limits
- See Rate Limits documentation for details
Server and processing errors
500 Internal Server Error
Example Response:
- Retry the request after a short delay
- Check if the issue persists
- Contact support if the error continues
503 Service Unavailable
Example Response:
- Wait and retry after some time
- Check service status page
- Implement retry logic with exponential backoff
AI model-specific errors
For AI content generation endpoints, the API may return additional error types:Model errors
Example model error:
SDK error types
The official Writer SDKs provide structured error handling with specific exception types:Python SDK errors
JavaScript/Node.js SDK errors
Error handling example
This example shows how to handle common error cases when making API requests using the Writer SDKs.Troubleshooting common errors
400 Bad request
- Verify all required parameters are included
- Check parameter value formats and constraints
- Ensure request body is valid JSON
401 Unauthorized
- Verify API key is correct and not expired
- Check that the API key has the required permissions
- Ensure the Authorization header is properly formatted
403 Forbidden
- Check if your organization/team has access to the requested resource
- Verify that the feature is enabled for your plan
- Contact support if you believe this is an error
429 Too many requests
- Implement exponential backoff retry logic
- Check your current usage against rate limits
- Consider upgrading your plan for higher limits
500 Internal server error
- Retry the request after a short delay
- Check the Writer status page for known issues
- Contact support if the error persists
Next steps
- API keys: learn how to authenticate with Writer APIs
- Rate limits: understand API rate limiting and quotas
- Python SDK: official Python library with built-in error handling
- Node.js SDK: official JavaScript/Node.js library with built-in error handling