> ## Documentation Index
> Fetch the complete documentation index at: https://wordsmithai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```json theme={null}
{
  "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."
}
```

<ParamField body="error_code" type="string" required>
  A machine-readable code identifying the type of error. Use this for programmatic error handling.
</ParamField>

<ParamField body="ws_api_error_code" type="string" required>
  Legacy alias for `error_code`. Both fields always contain the same value. New integrations should use `error_code`.
</ParamField>

<ParamField body="message" type="string">
  A human-readable description of the error. Useful for debugging and logging. Not all errors include a message.
</ParamField>

## 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](/api-reference/files/upload-url#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

```python theme={null}
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}")
```