Errors | Further AI

The Further AI API uses standard HTTP status codes and returns structured error responses to help you diagnose and resolve issues.

HTTP Status Codes

Status Code	Meaning	Description
`200 OK`	Success	The request was processed successfully
`401 Unauthorized`	Authentication failed	Invalid, expired, or missing bearer token
`403 Forbidden`	Access denied	Valid token but insufficient permissions for this resource
`404 Not Found`	Resource not found	The workflow ID or execution ID does not exist
`422 Unprocessable Entity`	Validation error	The request body is malformed or missing required fields
`429 Too Many Requests`	Rate limited	You have exceeded the API rate limit
`500 Internal Server Error`	Server error	An unexpected error occurred on the server

Error Response Format

Error responses follow a consistent structure:

1 {
2   "detail": "Description of what went wrong"
3 }

Validation Errors (422)

Validation errors include detailed information about which fields failed:

1 {
2   "detail": [
3     {
4       "loc": ["body", "client_id"],
5       "msg": "field required",
6       "type": "value_error.missing"
7     }
8   ]
9 }

Field	Description
`loc`	The location of the error (e.g., `["body", "field_name"]`)
`msg`	A human-readable error message
`type`	The error type identifier

Common Errors and Solutions

Authentication Errors

401 — Invalid or expired token

Cause: The bearer token in your Authorization header is invalid, expired, or missing.

Solution:

Verify the token has not expired (tokens are valid for 60 minutes)
Generate a new token using the /api/v1/oauth2/access_token endpoint
Ensure the Authorization header format is Bearer <token> (note the space after “Bearer”)

1 # Correct
2 headers = {"Authorization": f"Bearer {access_token}"}
3 
4 # Incorrect — missing "Bearer" prefix
5 headers = {"Authorization": access_token}

401 — Invalid client credentials

Cause: The client_id or client_secret provided to the token endpoint is incorrect.

Solution:

Double-check your credentials
Ensure there are no trailing whitespace characters
Contact your Further AI representative if you need new credentials

Request Errors

404 — Workflow not found

Cause: The workflow_id in the URL does not match any workflow in your account.

Solution:

Verify the workflow ID is correct
Ensure the workflow has not been deleted or renamed
Confirm you are using the correct account credentials

404 — Execution not found

Cause: The execution_id in the URL does not match any execution for the specified workflow.

Solution:

Verify the execution ID returned from the create execution call
Ensure you are querying the correct workflow ID
Note that execution IDs are scoped to a specific workflow

422 — Missing required fields

Cause: The request body is missing required fields or has an invalid format.

Solution:

For token requests: ensure both client_id and client_secret are provided
For multipart uploads: ensure files are attached with the field name files
For JSON requests: ensure file_urls is a non-empty array
Check that Content-Type matches the expected format for your workflow’s access type

422 — Invalid user_inputs keys

Cause: One or more keys in user_inputs do not follow the naming rules.

Solution:

Keys must use only lowercase letters, numbers, and underscores
Keys must start with a letter
See Text Inputs for valid key format

File Errors

422 — Unsupported file format

Cause: One or more uploaded files are in a format that is not supported.

Solution:

Supported formats include PDF, DOCX, XLSX, PNG, JPG, TIFF, CSV, TXT, EML, MSG, and ZIP
Ensure file extensions match the actual file content
ZIP files must contain supported file formats

422 — File access type mismatch

Cause: The request format does not match the workflow’s configured file access type.

Solution:

If the workflow expects multipart, send files as multipart/form-data
If the workflow expects public_urls, send a JSON body with file_urls
See File Access Configuration for details

Rate Limiting

429 — Too many requests

Cause: You have exceeded the API rate limit.

Solution:

Implement exponential backoff in your retry logic
Reduce the frequency of polling requests
Contact your Further AI representative if you need higher rate limits

Server Errors

500 — Internal server error

Cause: An unexpected error occurred on the Further AI server.

Solution:

Retry the request after a brief delay
If the error persists, contact Further AI support with the request details and any error messages
Check the Further AI status page for any ongoing incidents

Error Handling Best Practices

1 import time
2 import requests
3 
4 def make_api_request(url: str, headers: dict, max_retries: int = 3) -> dict:
5     """Make an API request with retry logic for transient errors."""
6     for attempt in range(max_retries):
7         response = requests.get(url, headers=headers)
8 
9         if response.status_code == 200:
10             return response.json()
11 
12         elif response.status_code == 401:
13             # Token expired — refresh and retry
14             raise AuthenticationError("Token expired. Please refresh.")
15 
16         elif response.status_code == 404:
17             # Resource not found — do not retry
18             raise NotFoundError(f"Resource not found: {response.json()}")
19 
20         elif response.status_code == 422:
21             # Validation error — do not retry
22             raise ValidationError(f"Invalid request: {response.json()}")
23 
24         elif response.status_code == 429:
25             # Rate limited — wait and retry
26             retry_after = int(response.headers.get("Retry-After", 60))
27             print(f"Rate limited. Retrying in {retry_after}s...")
28             time.sleep(retry_after)
29 
30         elif response.status_code >= 500:
31             # Server error — retry with backoff
32             wait = 2 ** attempt
33             print(f"Server error {response.status_code}. Retrying in {wait}s...")
34             time.sleep(wait)
35 
36         else:
37             response.raise_for_status()
38 
39     raise Exception(f"Request failed after {max_retries} retries")

Idempotency note: Creating an execution is not idempotent. If you retry a failed create-execution request, you may end up with duplicate executions. Always check whether the initial request succeeded before retrying.

Getting Help

If you encounter persistent errors or need assistance:

Note the HTTP status code, error message, and request details
Include the workflow_execution_id if the error relates to a specific execution
Contact your Further AI representative