“Authentication required. Provide Bearer token.”
Cause: Missing or invalid Authorization header. Solution: Include the Bearer token in the Authorization header:“Invalid or expired token”
Cause: JWT token has expired (checkexpires_in from /auth/token; currently 3600 seconds / 1 hour).
Solution: Get a new token from /auth/token:
“Missing required field: search_id”
Cause: Required field is missing from the request. Solution: Ensure all required fields are included:“date_of_birth must be in YYYY-MM-DD format”
Cause: Date format is incorrect. Solution: UseYYYY-MM-DD format:
“Court search ID and offense ID counts do not match the XML” (HTTP 422)
Cause: A non-emptyrecord.cases[] was sent with counts that do not match the parsed XML/record_json. Common with filtered UBS payloads that include fewer court search IDs / offense ID rows than the full record (e.g., 17 court search IDs and 22 offense IDs when XML has 24 cases and 32 charges). To exclude charges from the client decision, send the complete mapping and set is_excluded: true — do not drop those rows.
Solution: Either:
- Omit
cases[]or sendcases: []— evaluate all offenses (recommended when you do not need explicit mapping), or - Send the complete mapping — one row per offense, with distinct court search ID count equal to XML case count and total offense ID row count equal to total offense count, and
is_excludedon every row:
data.status: "validation_required", data.errors[] containing XML-Transformer failed: XML-Transformer HTTP error 422: Court search ID and offense ID counts do not match the XML: ..., and data.degradation.compliance_engine.status: "not_called". Do not retry — fix the payload. See Error Handling → court search ID / offense ID count mismatch.
”Failed to parse XML data”
Cause: Invalid or malformed XML in the request. Solution: Validate your XML before sending:Getting Help
If you encounter issues not covered here:- Check the API Reference for endpoint-specific details
- Verify your request format matches the Code Examples
- Review the Authentication Guide for token management