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:
{
  "tpe": "error_type",
  "errors": [
    {
      "description": "Human-readable error description",
      "key": "error.message.key",
      "extras": {}
    }
  ],
  "extras": {}
}

Response structure

FieldTypeDescription
tpestringError type identifier (for example, “BadRequest”, “Unauthorized”)
errorsarrayArray of error messages with details
extrasobjectAdditional error context and metadata
FieldTypeDescription
descriptionstringHuman-readable error description for developers
keystringMessage key for internationalization
extrasobjectAdditional context specific to the error

HTTP status codes

Writer APIs use standard HTTP status codes to indicate the nature of errors:
StatusError codeTypeDescriptionCommon causes
400BadRequestValidationInvalid request parameters or malformed request bodyMissing required fields, invalid format
401UnauthorizedAuthenticationMissing or invalid authentication credentialsMissing API key, invalid format
403ForbiddenAuthorizationValid credentials but insufficient permissionsInsufficient access rights
404NotFoundValidationRequested resource does not existInvalid resource ID, deleted resource
409ConflictValidationRequest conflicts with current stateDuplicate resource, version conflict
410GoneValidationResource was permanently removedDeleted/expired resource
413PayloadTooLargeValidationRequest body too largeExceeds configured size limits
422UnprocessableEntityValidationSemantically invalid requestFails business rules/constraints
429TooManyRequestsRate LimitingRate limit or quota exceededToo many requests per time period
500InternalServerErrorServerInternal server errorServer-side processing issue
503ServiceUnavailableServerService temporarily unavailableMaintenance, high load
507InsufficientStorageServerInsufficient storage to complete requestStorage quota exhausted

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
Error TypeHTTP StatusDescriptionPossible Causes
BadRequest400Invalid model parameterModel name not supported or malformed
InvalidInputParameters400Invalid prompt formatEmpty prompt or invalid encoding
InvalidContentType400Invalid parametersInvalid temperature, max_tokens, or other parameters
BadCredentials401Invalid API keyMissing or malformed API key
BadToken401API key expiredAPI key has expired
InsufficientAccessRights403Insufficient permissionsAPI key lacks required permissions
QuotaExceeded429Rate limit exceededToo many requests per minute
CompletionModelQuotaError429Quota exceededMonthly usage limit reached
CompletionModelUnavailableError500Model unavailableAI model temporarily unavailable
CompletionModelInternalError500Service overloadedHigh load, retry with backoff

Chat completions

Endpoint: POST /v1/chat/completions
Error TypeHTTP StatusDescriptionPossible Causes
BadRequest400Invalid messages formatMalformed messages array or role
InvalidInputParameters400Invalid model parameterModel not supported for chat
InvalidContentType400Invalid tool configurationMalformed tools or tool_choice
BadRequest400Invalid streaming parametersInvalid stream or stream_options
CompletionModelUnsafeRequestError400Content policy violationRequest contains prohibited content
BadCredentials401Authentication failedInvalid or missing API key
BadToken401Authentication failedInvalid or missing API key
InsufficientAccessRights403Model access deniedAccount lacks access to requested model
QuotaExceeded429Rate limit exceededToo many requests per minute
CompletionModelQuotaError429Model quota exceededModel-specific usage limit reached
CompletionModelInternalError500Model processing errorInternal error in model inference
CompletionModelUnavailableError503Model temporarily unavailableModel service is down for maintenance

Upload files

Endpoint: POST /v1/files
Error TypeHTTP StatusDescriptionPossible Causes
BadRequest400Invalid file formatUnsupported file type
InvalidInputParameters400File too largeFile exceeds size limit
InvalidContentType400Invalid file contentCorrupted or malformed file
BadCredentials401Authentication requiredMissing or invalid API key
BadToken401Authentication requiredMissing or invalid API key
InsufficientAccessRights403Upload permission deniedAccount lacks file upload permissions
BadRequest413Payload too largeRequest body exceeds size limit
QuotaExceeded429Upload rate limit exceededToo many file uploads per minute
InternalError500File processing errorError processing uploaded file
QuotaExceeded507Storage quota exceededAccount storage limit reached

Get file

Endpoint: GET /v1/files/{file_id}
Error TypeHTTP StatusDescriptionPossible Causes
BadCredentials401Authentication requiredMissing or invalid API key
BadToken401Authentication requiredMissing or invalid API key
InsufficientAccessRights403Access deniedNo permission to access this file
ResourceNotFound404File not foundFile ID doesn’t exist
ResourceNotFound410File goneFile has been deleted or expired

Create graph

Endpoint: POST /v1/knowledge-graphs
Error TypeHTTP StatusDescriptionPossible Causes
BadRequest400Invalid graph configurationMalformed graph parameters
InvalidInputParameters400Invalid graph nameName contains invalid characters
BadRequest400Duplicate graph nameGraph with this name already exists
BadCredentials401Authentication requiredMissing or invalid API key
BadToken401Authentication requiredMissing or invalid API key
InsufficientAccessRights403Graph creation deniedAccount lacks graph creation permissions
QuotaExceeded429Graph creation rate limitToo many graphs created per hour
InternalError500Graph creation failedInternal error creating graph

Add file to graph

Endpoint: POST /v1/knowledge-graphs/{graph_id}/files
Error TypeHTTP StatusDescriptionPossible Causes
BadRequest400Invalid file formatFile type not supported for graphs
InvalidInputParameters400File processing failedError parsing file content
BadCredentials401Authentication requiredMissing or invalid API key
BadToken401Authentication requiredMissing or invalid API key
InsufficientAccessRights403Graph access deniedNo permission to modify this graph
ResourceNotFound404Graph not foundGraph ID does not exist
BadRequest409File already in graphFile is already associated with graph
QuotaExceeded429File processing rate limitToo many files processed per minute

Query graph

Endpoint: POST /v1/knowledge-graphs/{graph_id}/query
Error TypeHTTP StatusDescriptionPossible Causes
BadRequest400Invalid query formatMalformed query parameters
InvalidInputParameters400Query too complexQuery exceeds complexity limits
BadCredentials401Authentication requiredMissing or invalid API key
BadToken401Authentication requiredMissing or invalid API key
InsufficientAccessRights403Query permission deniedNo permission to query this graph
ResourceNotFound404Graph not foundGraph ID doesn’t exist
QuotaExceeded429Query rate limit exceededToo many queries per minute
InternalError500Query processing errorInternal error processing query

Create application

Endpoint: POST /v1/applications
Error TypeHTTP StatusDescriptionPossible Causes
BadRequest400Invalid application configurationMalformed application parameters
InvalidInputParameters400Invalid blueprint configurationBlueprint syntax or configuration error
BadRequest400Duplicate application nameApplication with this name already exists
BadCredentials401Authentication requiredMissing or invalid API key
BadToken401Authentication requiredMissing or invalid API key
InsufficientAccessRights403Application creation deniedAccount lacks application creation permissions
QuotaExceeded429Application creation rate limitToo many applications created per hour
InternalError500Application creation failedInternal error creating application

Generate application job

Endpoint: POST /v1/applications/{app_id}/jobs
Error TypeHTTP StatusDescriptionPossible Causes
BadRequest400Invalid job parametersMalformed job request
InvalidInputParameters400Missing required inputsRequired input parameters not provided
BadCredentials401Authentication requiredMissing or invalid API key
BadToken401Authentication requiredMissing or invalid API key
InsufficientAccessRights403Job execution deniedNo permission to execute jobs for this app
ResourceNotFound404Application not foundApplication ID doesn’t exist
BadRequest409Job already runningApplication has a job already in progress
QuotaExceeded429Job execution rate limitToo many jobs executed per minute
InternalError500Job execution failedInternal error executing job

AI detect

Endpoint: POST /v1/tools/ai-detect
Error TypeHTTP StatusDescriptionPossible Causes
BadRequest400Invalid text inputEmpty or malformed text input
InvalidInputParameters400Text too longInput exceeds maximum length
BadCredentials401Authentication requiredMissing or invalid API key
BadToken401Authentication requiredMissing or invalid API key
InsufficientAccessRights403Tool access deniedAccount lacks AI detect permissions
QuotaExceeded429Detection rate limitToo many detection requests per minute
InternalError500Detection processing errorInternal error in AI detection

PDF parser

Endpoint: POST /v1/tools/pdf-parser
Error TypeHTTP StatusDescriptionPossible Causes
BadRequest400Invalid PDF fileCorrupted or unsupported PDF
InvalidInputParameters400PDF too largePDF exceeds size limits
BadRequest400PDF password protectedPDF requires password to access
BadCredentials401Authentication requiredMissing or invalid API key
BadToken401Authentication requiredMissing or invalid API key
InsufficientAccessRights403Parser access deniedAccount lacks PDF parser permissions
QuotaExceeded429Parser rate limitToo many parsing requests per minute
InternalError500PDF parsing errorInternal error parsing PDF
Endpoint: POST /v1/tools/web-search
Error TypeHTTP StatusDescriptionPossible Causes
BadRequest400Invalid search queryEmpty or malformed search query
InvalidInputParameters400Search query too longQuery exceeds maximum length
BadCredentials401Authentication requiredMissing or invalid API key
BadToken401Authentication requiredMissing or invalid API key
InsufficientAccessRights403Search access deniedAccount lacks web search permissions
QuotaExceeded429Search rate limitToo many search requests per minute
InternalError500Search processing errorInternal error in web search
InternalError503Search service unavailableExternal search service is down

Translate text

Endpoint: POST /v1/translate
Error TypeHTTP StatusDescriptionPossible Causes
BadRequest400Invalid language codesUnsupported source or target language
InvalidInputParameters400Invalid text inputEmpty or malformed text input
InvalidInputParameters400Text too longInput exceeds maximum length
BadCredentials401Authentication requiredMissing or invalid API key
BadToken401Authentication requiredMissing or invalid API key
InsufficientAccessRights403Translation access deniedAccount lacks translation permissions
QuotaExceeded429Translation rate limitToo many translation requests per minute
InternalError500Translation processing errorInternal error in translation
InternalError503Translation service unavailableTranslation service is down

Analyze images

Endpoint: POST /v1/vision/analyze
Error TypeHTTP StatusDescriptionPossible Causes
BadRequest400Invalid image formatUnsupported image type
InvalidInputParameters400Image too largeImage exceeds size limits
InvalidContentType400Invalid image contentCorrupted or malformed image
BadCredentials401Authentication requiredMissing or invalid API key
BadToken401Authentication requiredMissing or invalid API key
InsufficientAccessRights403Vision access deniedAccount lacks vision analysis permissions
QuotaExceeded429Vision rate limitToo many analysis requests per minute
InternalError500Image processing errorInternal error processing image
InternalError503Vision service unavailableVision service is down for maintenance

Error categories

Authentication and authorization errors

401 Unauthorized

StatusError codeTypeDescriptionCommon causes
401BadCredentialsAuthenticationInvalid API keyMissing Authorization header, invalid API key format
401BadTokenAuthenticationAPI key expiredAPI key has expired
Example Response:
{
  "tpe": "Unauthorized",
  "errors": [
    {
      "description": "Invalid token",
      "key": "fail.unauthorized.badToken",
      "extras": {}
    }
  ],
  "extras": {}
}
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

StatusError codeTypeDescriptionCommon causes
403InsufficientAccessRightsAuthorizationAPI key lacks required permissionsInsufficient permissions, wrong API key type
Example Response:
{
  "tpe": "Forbidden",
  "errors": [
    {
      "description": "Insufficient access rights",
      "key": "fail.forbidden.insufficientAccessRights",
      "extras": {}
    }
  ],
  "extras": {}
}
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

StatusError codeTypeDescriptionCommon causes
400BadRequestValidationInvalid request parametersMissing required fields, invalid format
400InvalidInputParametersValidationInvalid parameter valuesOut of range values, unsupported options
400InvalidContentTypeValidationInvalid content typeMalformed JSON, wrong content-type header
Example Response:
{
  "tpe": "BadRequest",
  "errors": [
    {
      "description": "Invalid input parameters",
      "key": "fail.badRequest.invalidParameters",
      "extras": {}
    }
  ],
  "extras": {}
}
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

StatusError codeTypeDescriptionCommon causes
404ResourceNotFoundValidationRequested resource doesn’t existInvalid resource ID, deleted resource
Example Response:
{
  "tpe": "NotFound",
  "errors": [
    {
      "description": "Resource is not found",
      "key": "fail.notFound.resource",
      "extras": {}
    }
  ],
  "extras": {}
}
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

StatusError codeTypeDescriptionCommon causes
429QuotaExceededRate LimitingToo many requests in time periodExceeding per-minute or per-day limits
429CompletionModelQuotaErrorRate LimitingModel quota exceededMonthly usage limit reached
Example Response:
{
  "tpe": "TooManyRequests",
  "errors": [
    {
      "description": "Quota exceeded",
      "key": "fail.tooManyRequests.quotaExceeded",
      "extras": {}
    }
  ],
  "extras": {}
}
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

StatusError codeTypeDescriptionCommon causes
500InternalErrorServerUnexpected server errorServer-side processing issue
500CompletionModelInternalErrorServerModel processing errorInternal error in model inference
Example Response:
{
  "tpe": "InternalServerError",
  "errors": [
    {
      "description": "Internal server error",
      "key": "fail.internalServerError.generic",
      "extras": {}
    }
  ],
  "extras": {}
}
How to Fix:
  • Retry the request after a short delay
  • Check if the issue persists
  • Contact support if the error continues

503 Service Unavailable

StatusError codeTypeDescriptionCommon causes
503CompletionModelUnavailableErrorServerModel temporarily unavailableModel service is down for maintenance
Example Response:
{
  "tpe": "ServiceUnavailable",
  "errors": [
    {
      "description": "Service temporarily unavailable",
      "key": "fail.serviceUnavailable.temporary",
      "extras": {}
    }
  ],
  "extras": {}
}
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

Error TypeDescription
CompletionModelUnavailableErrorAI model is temporarily unavailable
CompletionModelInternalErrorInternal error in model processing
CompletionModelQuotaErrorModel usage quota exceeded
CompletionModelUnauthorizedErrorInvalid model access credentials
CompletionModelUnderlyingRequestErrorError in underlying model request
CompletionModelUnsafeRequestErrorRequest contains unsafe content
CompletionModelNoPredictionErrorModel couldn’t generate a prediction
Example model error:
{
  "tpe": "CompletionModelQuotaError",
  "errors": [
    {
      "description": "Model usage quota exceeded",
      "key": "fail.model.quotaExceeded",
      "extras": {}
    }
  ],
  "extras": {}
}

SDK error types

The official Writer SDKs provide structured error handling with specific exception types:

Python SDK errors

Error TypeHTTP StatusDescription
APIConnectionErrorN/ANetwork connectivity issues, timeouts, DNS failures
APITimeoutErrorN/ARequest timeout exceeded
BadRequestError400Invalid request parameters or malformed request body
AuthenticationError401Missing or invalid API key
PermissionDeniedError403Valid API key but insufficient permissions
NotFoundError404Requested resource doesn’t exist
UnprocessableEntityError422Request is well-formed but contains semantic errors
RateLimitError429Rate limit or quota exceeded
InternalServerError≥500Internal server error

JavaScript/Node.js SDK errors

Error TypeHTTP StatusDescription
connection_errorN/ANetwork connectivity issues, timeouts, DNS failures
timeout_errorN/ARequest timeout exceeded
bad_request400Invalid request parameters or malformed request body
authentication_error401Missing or invalid API key
permission_denied403Valid API key but insufficient permissions
not_found404Requested resource doesn’t exist
unprocessable_entity422Request is well-formed but contains semantic errors
rate_limit_error429Rate limit or quota exceeded
internal_server_error≥500Internal server error

Error handling example

This example shows how to handle common error cases when making API requests using the Writer SDKs.
from writerai import Writer
import writerai

# Initialize the client. If you don't pass the `api_key` parameter,
# the client looks for the `WRITER_API_KEY` environment variable.
client = Writer()

try:
    response = client.chat.chat(
        messages=[
            {
                "role": "user",
                "content": "Write a haiku about programming"
            }
        ],
        model="palmyra-x5"
    )
    print("Success:", response.choices[0].message.content)
    
except writerai.APIConnectionError as e:
    print("Network error:", e)
    print("Cause:", e.__cause__)
    
except writerai.RateLimitError as e:
    print("Rate limited:", e)
    print("Status code:", e.status_code)
    # SDK automatically handles retries with exponential backoff
    
except writerai.AuthenticationError as e:
    print("Authentication failed:", e)
    print("Status code:", e.status_code)
    # Refresh API key or redirect to login
    
except writerai.BadRequestError as e:
    print("Invalid request:", e)
    print("Status code:", e.status_code)
    
except writerai.InternalServerError as e:
    print("Server error:", e)
    print("Status code:", e.status_code)
    # SDK automatically retries 5xx errors
    
except writerai.APIStatusError as e:
    print("API error:", e)
    print("Status code:", e.status_code)
    print("Response:", e.response)

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
I