Skip to main content
The Task API may return various warnings and errors during operation. This page documents the possible error types you might encounter when using the API.

​
Errors

Errors result in a failure to process your request and are returned with appropriate HTTP status codes (4xx or 5xx).
ErrorDescriptionResolution
Invalid JSON SchemaThe JSON schema provided in the task spec for input or output is invalid.Review your schema against JSON Schema specifications and ensure it follows the required format.
Task Spec + Input Too LongThe combined task specification and input exceeds 15,000 characters.Reduce the size of your task spec or input data. Consider splitting into multiple tasks if necessary.
Too-Complex Output SchemaThe output schema exceeds allowed complexity in terms of nesting depth or number of fields.Simplify your output schema by reducing nested levels to 3 or less.

​
Warnings

Warnings indicate potential issues that don’t prevent the request from being processed but may affect results.
WarningDescriptionResolution
Input Fails ValidationThe provided input does not conform to the input schema.Verify your input against the schema requirements and make necessary adjustments.
Task Spec + Input Over Size LimitThe combined task specification and input exceeds the character limit.Consider optimizing your input or task spec for better performance.
Too Many Output FieldsThe number of requested output fields exceeds the recommended limit.Consider reducing the number of output fields.

​
Warning Handling

The Task API uses a warning system to provide guidance without blocking execution. Warnings are generated during validation and can be handled in two ways:

​
Basis Properties Warning

The following properties are provided by default through the task’s run basis and should not be defined in the output schema:
  • citations
  • confidence
  • evidence
  • reasoning
  • source
  • sources
  • source_urls
Including these in your output schema will trigger a warning, as it’s recommended to use FieldBasis in the run output instead.

​
Error Reference

Status CodeMeaningRetry?DescriptionResolution Approach
401UnauthorizedNoInvalid or missing credentialsVerify API key and authentication headers
402Payment RequiredNoInsufficient credit in accountAdd credits to account
403ForbiddenNoInvalid processor in requestCheck processor availability and permissions
404Not FoundNoRun ID or resource not foundVerify run ID and resource existence
408Request TimeoutYesSynchronous request timed outUse asynchronous polling
422Unprocessable ContentNoRequest validation failedReview error details and validate schema
429Too Many RequestsYesRate limited or quota exceededImplement exponential backoff
500Internal Server ErrorYesServer-side processing errorRetry with backoff, contact support if persistent
502Bad GatewayYesUpstream service errorRetry, usually temporary
503Service UnavailableYesService temporarily unavailableRetry with backoff

​
Error Response Format

All errors return a consistent JSON structure: 
{
  "error": {
    "message": "Human-readable error description",
    "detail": {
      // Additional error-specific information
    }
  }
}
For validation errors (422), the detail field contains specific information about which fields failed validation and why.