Reference

Troubleshooting Errors

When a job fails during processing, error details are available in the job details response. You can retrieve job details using the GET /api/v1/jobs/{job_id} or GET /api/v1/jobs/{job_id}/status endpoints.

Locating Error Information:

In the job details JSON response (see Job Details for full structure), error information is found in the extract.exception object:

1{
2  "job_id": "12345",
3  "status": "failed",
4  "extract": {
5    "exception": {
6      "exception_name": "InvalidManifestException",
7      "exception_desc": "Manifest CSV is missing 'subject_id' column"
8    }
9  }
10}

The exception_name identifies the error type, and exception_desc provides specific details about what went wrong. Use the exception types below to diagnose and resolve issues:

Exception Types

General Errors

InternalServerError

  • Description: An unexpected internal error occurred during processing
  • Example message: "An internal error occurred. Please contact support for assistance."
  • Resolution: Contact support with your job ID for assistance

Input and Validation Errors

InvalidS3Credentials

  • Description: Unable to access your S3 bucket due to credential or permission issues
  • Example message: "Unable to access file: {error_code}. Please verify S3 credentials and permissions."
  • Common causes:
    • Invalid AWS access key ID or secret access key
    • Expired session token
    • Insufficient IAM permissions on the bucket or objects
    • Bucket policy blocking access
  • Resolution: Verify your AWS credentials are correct and have the required permissions (s3:GetObject, s3:ListBucket) for your input bucket and paths

InvalidManifestException

  • Description: The manifest file is invalid or malformed
  • Common causes:
    • File format issues (not CSV, invalid encoding, wrong delimiter)
    • File size or row count exceeding limits
    • Missing required columns (document, subject_id)
    • Empty required values
  • Resolution: Review the specific error message and correct your manifest file. See Troubleshooting Input Validation Errors for detailed guidance on each validation error

ManifestValidationError

  • Description: One or more rows in the manifest failed data validation
  • Common causes:
    • Invalid data types in columns
    • Values exceeding maximum length (255 characters)
    • Invalid date formats (must be ISO 8601: YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS)
    • Missing required field values
  • Resolution: Review the error message for specific row and field details. Correct the data in your manifest and resubmit. See Validation Schema for complete field requirements

FileInManifestNotFoundException

  • Description: One or more files listed in the manifest were not found in your input bucket
  • Example message: "The following files were listed in the file manifest but were not found in the customer input bucket (prefix: {prefix}):\n{file_list}"
  • Resolution: Verify that:
    • All file paths in the document column exactly match the S3 object keys in your bucket
    • Files are located in the correct input bucket path
    • File paths include any necessary subdirectories

InvalidRegionException

  • Description: An invalid AWS region was specified in the job parameters
  • Example message: "Invalid AWS region '{region}'. {additional_details}"
  • Resolution: Specify a valid AWS region code (e.g., us-east-1, us-west-2) in your job parameters