Errors

Understanding error responses from the 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

1. Check the HTTP status code to determine the error category (4xx = client error, 5xx = server error).
2. Switch on error_code for specific handling logic (e.g., retrying on rate_limit_exceeded, re-uploading on invalid_upload_job).
3. 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}")