Error codes

​

Error code reference

​

Error types

• Authentication and authorization errors
• Request validation errors
• Rate limiting and quota errors
• Server and processing errors
• Error codes by service

​

Error response format

{
  "tpe": "error_type",
  "errors": [
    {
      "description": "Human-readable error description",
      "key": "error.message.key",
      "extras": {}
    }
  ],
  "extras": {}
}

​

Response structure

​

HTTP status codes

​

Error codes by service

​

Error categories

​

Authentication and authorization errors

​

401 Unauthorized

{
  "tpe": "Unauthorized",
  "errors": [
    {
      "description": "Invalid token",
      "key": "fail.unauthorized.badToken",
      "extras": {}
    }
  ],
  "extras": {}
}

• 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

{
  "tpe": "Forbidden",
  "errors": [
    {
      "description": "Insufficient access rights",
      "key": "fail.forbidden.insufficientAccessRights",
      "extras": {}
    }
  ],
  "extras": {}
}

• 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

{
  "tpe": "BadRequest",
  "errors": [
    {
      "description": "Invalid input parameters",
      "key": "fail.badRequest.invalidParameters",
      "extras": {}
    }
  ],
  "extras": {}
}

• 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

{
  "tpe": "NotFound",
  "errors": [
    {
      "description": "Resource is not found",
      "key": "fail.notFound.resource",
      "extras": {}
    }
  ],
  "extras": {}
}

• 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

{
  "tpe": "TooManyRequests",
  "errors": [
    {
      "description": "Quota exceeded",
      "key": "fail.tooManyRequests.quotaExceeded",
      "extras": {}
    }
  ],
  "extras": {}
}

• 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

{
  "tpe": "InternalServerError",
  "errors": [
    {
      "description": "Internal server error",
      "key": "fail.internalServerError.generic",
      "extras": {}
    }
  ],
  "extras": {}
}

• Retry the request after a short delay
• Check if the issue persists
• Contact support if the error continues

​

503 Service Unavailable

{
  "tpe": "ServiceUnavailable",
  "errors": [
    {
      "description": "Service temporarily unavailable",
      "key": "fail.serviceUnavailable.temporary",
      "extras": {}
    }
  ],
  "extras": {}
}

• Wait and retry after some time
• Check service status page
• Implement retry logic with exponential backoff

​

AI model-specific errors

​

Model errors

{
  "tpe": "CompletionModelQuotaError",
  "errors": [
    {
      "description": "Model usage quota exceeded",
      "key": "fail.model.quotaExceeded",
      "extras": {}
    }
  ],
  "extras": {}
}

​

SDK error types

​

Python SDK errors

​

JavaScript/Node.js SDK errors

​

Error handling example

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