Skip to main content
This page provides a comprehensive reference for all error codes, HTTP status codes, and error handling patterns used across Writer APIs.

Error code reference

Quickstart: Most issues fall into these categories. Check here first!

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:

Error response format

All API endpoints return errors in a consistent JSON format:

Response structure

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.

Text generation

Endpoint: POST /v1/completion

Chat completions

Endpoint: POST /v1/chat/completions

Upload files

Endpoint: POST /v1/files

Get file

Endpoint: GET /v1/files/{file_id}

Create graph

Endpoint: POST /v1/knowledge-graphs

Add file to graph

Endpoint: POST /v1/knowledge-graphs/{graph_id}/files

Query graph

Endpoint: POST /v1/knowledge-graphs/{graph_id}/query

Create application

Endpoint: POST /v1/applications

Generate application job

Endpoint: POST /v1/applications/{app_id}/jobs

PDF parser

Endpoint: POST /v1/tools/pdf-parserEndpoint: POST /v1/tools/web-search

Analyze images

Endpoint: POST /v1/vision/analyze
Guardrail errors occur when content is blocked by configured safety controls. For more information, see Configure guardrails.

Content blocked by guardrail

Example guardrail error:
How to Fix:
  • 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:
How to Fix:
  • 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:
How to Fix:
  • 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:
How to Fix:
  • 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:
How to Fix:
  • 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:
How to Fix:
  • 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:
How to Fix:
  • Retry the request after a short delay
  • Check if the issue persists
  • Contact support if the error continues

503 Service Unavailable

Example Response:
How to Fix:
  • 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