Errors - Wordsmith API

All Wordsmith API error responses follow a consistent JSON format. This page documents the error envelope, all possible error codes, and how to handle errors in your integration.

Error Response Format

Every error response includes a JSON body with the following structure:

{
  "error_code": "invalid_request_body",
  "ws_api_error_code": "invalid_request_body",
  "message": "Request body is invalid. Ensure it is valid JSON with a 'question' field."
}

error_code

string

required

A machine-readable code identifying the type of error. Use this for programmatic error handling.

ws_api_error_code

string

required

Legacy alias for error_code. Both fields always contain the same value. New integrations should use error_code.

message

string

A human-readable description of the error. Useful for debugging and logging. Not all errors include a message.

Error Codes Reference

Authentication & Authorization

HTTP Status	Error Code	Description
401	`unauthorized`	API key is missing, malformed, or invalid.
403	`forbidden`	The API key does not have permission to perform this action.

Request Validation

HTTP Status	Error Code	Description
400	`invalid_request_body`	The request body is not valid JSON or is missing required fields.
400	`bad_request`	Generic bad request. Check the `message` field for details.

File Upload

HTTP Status	Error Code	Description
400	`invalid_upload_job`	The `upload_job_id` is not recognized, has expired, or the file was not uploaded to the presigned URL. Generate a new upload URL and retry.
400	`unsupported_file_type`	The specified `content_type` is not supported. See supported file types.

Questions & Sessions

HTTP Status	Error Code	Description
400	`session_still_processing`	A previous question in this session has not finished processing. Wait for it to complete before submitting a new question.
404	`resource_not_found`	The requested assistant, question, or other resource was not found.

Rate Limiting & Credits

HTTP Status	Error Code	Description
429	`rate_limit_exceeded`	Too many requests. Back off and retry after a short delay. The response may include `next_tier_with_more_credits` if a higher plan is available.
402	`insufficient_credits`	Your account does not have enough credits for this operation. The response includes `credits_needed` and `total_remaining`.

Server Errors

HTTP Status	Error Code	Description
500	`internal_error`	An unexpected server error occurred. If this persists, please contact support.

Handling Errors

Recommended Approach

Check the HTTP status code to determine the error category (4xx = client error, 5xx = server error).
Switch on error_code for specific handling logic (e.g., retrying on rate_limit_exceeded, re-uploading on invalid_upload_job).
Log the message for debugging purposes.

Retry Strategy

429 (rate_limit_exceeded): Retry with exponential backoff.
500 (internal_error): Retry up to 3 times with backoff. If the error persists, contact support.
400/401/403/404: Do not retry — fix the request or credentials first.

Example Error Handling

import requests

response = requests.post(
    "https://api.wordsmith.ai/api/v1/assistants/default/questions",
    headers={"Authorization": "Bearer sk-ws-api1-your_key"},
    json={"question": "Review this contract"},
)

if response.status_code == 200:
    result = response.json()
elif response.status_code == 429:
    # Back off and retry
    retry_after_delay()
else:
    error = response.json()
    error_code = error.get("error_code", "unknown")
    message = error.get("message", "No details available")
    print(f"API error ({error_code}): {message}")

​Error Response Format

​Error Codes Reference

​Authentication & Authorization

​Request Validation

​File Upload

​Questions & Sessions

​Rate Limiting & Credits

​Server Errors

​Handling Errors

​Recommended Approach

​Retry Strategy

​Example Error Handling

Error Response Format

Error Codes Reference

Authentication & Authorization

Request Validation

File Upload

Questions & Sessions

Rate Limiting & Credits

Server Errors

Handling Errors

Recommended Approach

Retry Strategy

Example Error Handling