Error Codes & Rate Limits

Error Response Format

All error responses return a JSON object with a detail field containing a human-readable message:

{
  "detail": "Document not found"
}

For validation errors (422), the response includes field-level detail:

{
  "detail": [
    {
      "loc": ["body", "project_id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

HTTP Status Codes

Code	Meaning	When It Occurs
200	OK	Request succeeded
201	Created	Resource created successfully (e.g., new project)
202	Accepted	Request accepted for async processing (e.g., document upload)
204	No Content	Success with no response body (e.g., delete)
400	Bad Request	Malformed request body or invalid parameters
401	Unauthorized	Missing, invalid, or expired access token
403	Forbidden	Valid token but insufficient permissions for this resource
404	Not Found	Resource does not exist or is not accessible to the caller
409	Conflict	Resource already exists (e.g., duplicate project name)
422	Unprocessable Entity	Request is well-formed but contains validation errors
429	Too Many Requests	Rate limit exceeded (reserved for future use)
500	Internal Server Error	Unexpected server failure

Common Error Scenarios

401 Unauthorized — Invalid Credentials

curl -X POST https://<your-instance>/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"client_id": "wrong", "client_secret": "wrong"}'

{
  "detail": "Invalid credentials"
}

Resolution: Verify the client ID and secret. If the credential was deleted or rotated, create a new one in Settings > Security > API Credentials.

401 Unauthorized — Expired Token

{
  "detail": "Token has expired"
}

Resolution: Exchange your client credentials for a new access token. See Authentication.

403 Forbidden — Insufficient Permissions

{
  "detail": "You do not have permission to access this resource"
}

Resolution: The API credential's associated user does not have access to the requested project or resource. Check project membership and user roles.

403 Forbidden — Ethical Wall

{
  "detail": "Access denied by ethical wall policy"
}

Resolution: The requested resource is restricted by an ethical wall configuration. Ethical walls prevent cross-matter access in conflict-sensitive environments. Contact your administrator if you believe this is an error.

404 Not Found

{
  "detail": "Document not found"
}

Resolution: The resource ID is invalid, the resource has been deleted, or the caller does not have access to the containing project.

422 Unprocessable Entity — Validation Error

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "ensure this value has at most 255 characters",
      "type": "value_error.any_str.max_length"
    }
  ]
}

Resolution: Check the request body against the expected schema. The loc field indicates which parameter failed validation.

500 Internal Server Error

{
  "detail": "Internal server error"
}

Resolution: This indicates an unexpected backend failure. Check the backend logs (docker logs cl-backend) for details. If the issue persists, see Troubleshooting.

Rate Limits

Contract Lucidity does not currently enforce hard rate limits. However, to ensure stable performance for all users, follow these guidelines:

Resource	Recommended Limit	Notes
Token requests	10 per minute	Cache tokens and reuse until expiry
Document uploads	10 per minute	Each upload triggers a full AI pipeline run
Read requests	100 per minute	GET requests for documents, reports, projects
Polling interval	5 seconds minimum	When polling for pipeline status, space requests at least 5 seconds apart

tip

If you are uploading documents in bulk, upload them sequentially rather than in parallel. The worker processes documents based on CELERY_CONCURRENCY (default: 2), so uploading faster than the system can process creates a backlog without improving throughput.

Hard rate limits with 429 responses and Retry-After headers may be introduced in a future release.