Error Handling

This page covers error responses from both the Context API and the Data Curation API.

HTTP status codes

Status code	Meaning
`200 OK`	Request completed successfully.
`202 Accepted`	Processing request accepted; results not yet available. Poll the results endpoint.
`400 Bad Request`	The request body is malformed or a required field is missing. Check the response body for details.
`401 Unauthorized`	The `Authorization` header is missing or the token is expired. Request a new token (see Authentication for more information).
`403 Forbidden`	The token is valid but the account does not have the required role for this API (see Authentication for more infomration).
`404 Not Found`	The requested resource (`job_id`, `processingId`, `objectKey`, or `documentId`) does not exist or is inaccessible.
`500 Internal Server Error`	An unexpected server-side error occurred. Retry the request; if the error persists, contact support.

Data Curation API errors

Job status values

When a job fails during processing, the status field returns "Error". The job cannot be recovered; submit a new presign request to retry.

For a complete list of job status values and their meanings, see the Job status values section in the Curating Documents guide.

Example: unsupported or corrupt file

When GET /data-curation/status/{jobId} returns "Error" because the uploaded file could not be processed, downloading the result file from get_url returns an error payload instead of structured output:

{
  "message": "Error: The file was not supported, corrupt, or blank."
}

Causes: The file is corrupt, blank, or in a format not supported by the processing pipeline.

How to resolve: Verify the file is not corrupt and is a supported file type. Re-upload and retry by submitting a new presign request.

Example: job not found

When GET /data-curation/status/{jobId} is called with an unknown or inaccessible job ID:

{
  "message": "Job not found"
}

This response is returned for both non-existent jobs and jobs belonging to a different environment (the API does not distinguish between the two to prevent information leakage).

Context API errors

Request validation errors (400 Bad Request)

The Context API validates all /content/process requests before accepting them. When validation fails, the API returns 400 Bad Request with a detailed error message.

Common validation errors

Validation rule	Error message
Empty `objectKeys` list	`ObjectKeys list cannot be null or empty`
Duplicate `objectKeys`	`ObjectKeys list must contain only distinct values`
Too many `objectKeys`	`ObjectKeys list can only contain up to 30 elements`
Empty `objectKeys` element	`ObjectKeys elements cannot be empty`
Missing path and documentId	`ObjectKeys elements must contain non-empty path or documentId`
`documentId` too long	`ObjectKeys documentId length cannot exceed 512 characters`
Mixed path and documentId	`ObjectKeys cannot contain both path and documentId in the same request`
v2 payload with string arrays	`When version is 'context.api/v2', objectKeys must be provided as objects, not as string arrays`
Empty `actions`	`'Actions' must not be empty.`
Duplicate action names	`'Actions' must contain unique, non-empty names.`
Unknown action name	`Unknown action '{action}'. Actions array must contain only known actions.`
Case mismatch	`Unknown action '{action}'. Did you mean '{expected}'? Note: v1 uses kebab-case (e.g., 'text-classification'), v2 uses camelCase (e.g., 'textClassification').`
Unsupported v1 action	`Input contains unsupported action/s for v1`
Missing `classes` for classification	`When {action} action is specified, classes array must contain at least 2 distinct classes`
Duplicate classes	`Classes array must contain only distinct values`
Classification with object but no classes	`When {action} action is specified as object, classes property must be provided and contain at least 2 distinct classes`
Missing `kSimilarMetadata` for metadata generation	`When {action} action is specified, kSimilarMetadata cannot be null or empty`
Metadata generation with object but no metadata	`When {action} action is specified as object, kSimilarMetadata property must be provided`
Invalid `maxWordCount`	`MaxWordCount must be greater than 0`
`maxWordCount` on unsupported action	`MaxWordCount can only be provided for 'imageDescription' or 'textSummarization'.`
Action with object and invalid maxWordCount	`{action} action maxWordCount must be greater than 0`
Unsupported action property	`{action} action does not support the following properties: {properties}`
Image action with non-image file	`When image processing action is specified, all object keys must point to supported image files`
Invalid `version` format	`Version must be null or match 'context.api/v{number}'.`
Unsupported version	`Version {version} is not supported.`
Mixed legacy and structured payload	`Payload cannot mix legacy and structured formats.`
Structured payload without version	`Version must be provided when using structured payload format.`
Structured payload with legacy version	`Structured payload requires a supported structured version.`
Legacy payload with structured version	`Version {version} cannot be used with legacy payload format.`

Request errors (400 Bad Request)

Objects not found or incorrect content type

When POST /content/process is called with objectKeys that don't exist in the Cloud Content Repository or have an incorrect content type for the requested actions, the API returns:

{
  "title": "Request Processing Error",
  "detail": "Some objects specified in ObjectKeys do not exist or have an incorrect content type",
  "notExistingObjects": ["path/to/missing/file.pdf", "path/to/wrong/type.txt"]
}

Causes: One or more objectKeys in the request do not exist in the Cloud Content Repository, or the files have content types incompatible with the requested actions (for example, requesting image actions on a text file).

How to resolve: Verify all objectKeys exist by checking the upload response or the Cloud Content Repository. Ensure file types match the requested actions (image actions require image files, text actions require text-based files).

General processing errors

When GET /{processingId}/results detects general processing errors across all actions:

{
  "title": "Request Processing Error",
  "detail": "Content processing failed"
}

Causes: All actions encountered errors during processing.

How to resolve: Check the detailed error information by polling the results endpoint again, or review the error fields in the per-action results for specific failure causes.

Not found errors (404)

Processing ID not found

When GET /{processingId}/results is called with an unknown or inaccessible processing ID:

{
  "title": "Request Processing Error",
  "detail": "Content processing result with specified ID does not exist"
}

Causes: The processingId does not exist or belongs to a different tenant.

How to resolve: Verify the processingId from the initial POST /content/process response. The API does not distinguish between non-existent and unauthorized IDs for security reasons.

Internal server errors (500)

When an unhandled exception occurs in the Context API, the API returns a standardized problem details response:

{
  "status": 500,
  "title": "Internal server error",
  "detail": "An error occured when processing the request"
}

How to resolve: Retry the request. If the error persists, contact support.

Queue processing error

When the request cannot be queued for processing:

{
  "status": 500,
  "title": "Request Processing Error",
  "detail": "An error occurred while sending a message to the queue"
}

Causes: A temporary infrastructure issue prevented the request from being queued.

How to resolve: Retry the request. If the error persists after multiple attempts, contact support.

Processing errors

In case an error occurs during document processing or when executing an action, corresponding error objects are stored in place of the expected action result. Each type of action error follows the same schema.

Format of a Failed Action

When a Context API action fails, the result object for that action has isSuccess: false and includes an error object. Other actions in the same request are unaffected.

{
  "isSuccess": false,
  "result": null,
  "error": {
    "errorType": "UnexpectedError",
    "message": "The given key 'statusCode' was not present in the dictionary."
  }
}

Action error types

`errorType`	Meaning	How to resolve
`UnexpectedError`	An unhandled server-side error occurred during action processing.	Retry the request. If it persists, contact support with the processing ID.
`GuardrailViolation`	The content triggered an AI safety guardrail.	Rephrase the content or contact support (see Guardrails for more information).
`UnsupportedFileType`	The uploaded file type is not supported for this action.	Check the list of supported formats in the Context API reference.
`ObjectKeyNotFound`	The `objectKey` or `documentId` provided in the request does not exist in Content Lake.	Verify the identifier by re-uploading the file and using the returned `objectKey` or confirming the `documentId` exists.
`Timeout`	The action did not complete within the allowed processing time.	Retry the request. If the issue persists for large files, consider splitting the content.
`AuthorizationError`	The action is not authorized for your account or subscription.	Verify that your account has access to the requested action. Contact support if the issue persists.
`ValidationError`	The file does not meet the constraints for the requested action (see the following image validation for more information).	Check the file against the constraints for the action and re-upload.

Image validation errors

When image processing actions fail validation, the error message provides specific details:

Error message	Constraint violated	Applies to
`Image size exceeds 5 MB.`	File size > 5 MB	`imageClassification`, `imageDescription`, `imageMetadataGeneration`, `namedEntityRecognitionImage`
`Image resolution exceeds 8000 x 8000 pixels.`	Width × Height > 8000 × 8000 pixels	`imageClassification`, `imageDescription`, `imageMetadataGeneration`, `namedEntityRecognitionImage`
`Image size exceeds 25 MB.`	File size > 25 MB	`imageEmbeddings`
`Image resolution exceeds 2048 x 2048 x 3 pixels.`	Width × Height > 2048 × 2048 (with 3 channels)	`imageEmbeddings`
`Aspect ratio {ratio} is out of range (0.25 - 4.0).`	Width ÷ Height < 0.25 or > 4.0	`imageEmbeddings`
`Unable to retrieve image resolution data. Please provide a valid image file.`	Image metadata cannot be extracted	All image actions

Processing status values

The top-level status field in a results response reflects the aggregate outcome across all actions:

`status`	Meaning
`PROCESSING`	Processing is still in progress. The `inProgress` field is `true`. Continue polling.
`SUCCESS`	All requested actions completed successfully.
`PARTIAL_FAILURE`	Some actions succeeded and some failed. Check per-action `isSuccess` fields.
`FAILURE`	All actions failed. Check per-action `error` fields.

Example: processing in progress (202 response)

{
  "id": "9984baa7-9948-4c03-bc06-313dd858c5ac",
  "timestamp": "2025-06-04T16:18:34.2353763+00:00",
  "status": "PROCESSING",
  "inProgress": true
}

Example: partial failure

{
  "id": "156e4a8a-e9c8-41c0-95f0-7039982236f3",
  "timestamp": "2025-03-24T15:45:14.104323+01:00",
  "results": [
    {
      "objectKey": "testing/documents/fedex.pdf",
      "textSummary": {
        "isSuccess": false,
        "result": null,
        "error": {
          "errorType": "UnexpectedError",
          "message": "The given key 'statusCode' was not present in the dictionary."
        }
      },
      "textClassification": {
        "isSuccess": true,
        "result": "invoice",
        "error": null
      }
    }
  ],
  "status": "PARTIAL_FAILURE"
}

---

## Guardrail violations

Guardrails are AI safety controls applied during Context API enrichment. When a guardrail triggers, the API returns a `GuardrailViolation` error instead of a partial result.

```json
{
  "isSuccess": false,
  "result": null,
  "error": {
    "errorType": "GuardrailViolation",
    "message": "The content was blocked by a guardrail policy."
  }
}

How to resolve: Review the content for policy-violating material. Rephrase or remove the offending content and retry. If the issue persists, contact support.

See Guardrails for the full list of covered actions and guardrail behavior details.

HTTP status codes​

Data Curation API errors​

Job status values​

Example: unsupported or corrupt file​

Example: job not found​

Context API errors​

Request validation errors (400 Bad Request)​

Common validation errors​

Request errors (400 Bad Request)​

Objects not found or incorrect content type​

General processing errors​

Not found errors (404)​

Processing ID not found​

Internal server errors (500)​

Queue processing error​

Processing errors​

Format of a Failed Action​

Action error types​

Image validation errors​

Processing status values​

Example: processing in progress (202 response)​

Example: partial failure​