Start with the smallest reproducible request
- 1Call GET /health with the same credential and environment
- 2Call GET /datasets and confirm the dataset is visible
- 3Capture status, request_id, route, and timestamp
- 4Reduce the failing query to release_id and limit=1
- 5Compare the request with the canonical OpenAPI operation
Common symptoms
| Symptom | Likely cause | Next check |
|---|---|---|
| 401 on every route | Missing, wrong-environment, expired, or revoked key | Authorization header and key rotation state |
| 404 for a release | Wrong dataset/release pair or unavailable release | List releases for the dataset |
| Empty query result | Exact filter does not match or wrong release selected | Remove filters and request one row |
| partial=true | Selected release has incomplete quality status | Inspect the release manifest and policy |
| Build remains queued | Capacity or upstream dependency delay | Build age, health, and operational deadline |
| Duplicate builds | POST retried after ambiguous timeout | List builds and reconcile recent requests |
Schema mismatch after a release change
Fetch the dataset definition and release manifest again. Compare dataset_version, definition_version, schema_version, required fields, and field types with the last successful import. Unknown optional fields should not fail tolerant readers, but a missing required field must stop the import visibly.