Errors, limits and retries
Handle failures explicitly and keep imports recoverable.
| Status | Likely meaning | What to do |
|---|---|---|
| 400 | Unsupported or missing parameters; invalid query-key auth | Validate against the endpoint schema |
| 401 | Missing, invalid, expired or revoked authentication | Reconnect or verify the server-side key |
| 403 | Account or feature is not entitled | Check access; do not retry unchanged |
| 404 | Institution, resource or dataset was not found | Check identity; do not invent an empty record |
| 409 | Pinned release or source version cannot be served consistently | Discard the partial import and restart from page one |
| 429 | Rate limit reached | Honor Retry-After when present; reduce concurrency |
| 5xx | Server or source is unavailable | Retry briefly with backoff, then surface the failure |
A successful response uses ok: true. Errors use ok: false and an error value; a trace_id is included when available. Keep the HTTP status and safe trace ID for support. Do not assume every failure response has the same JSON shape: an upstream or hosting error may return another content type.
Bounded retry policy
For idempotent reads, use a timeout, exponential backoff with jitter and a small maximum attempt count. Do not retry all status codes. Persist the job's failed state instead of looping indefinitely. A signed single-use download token should be replaced with a fresh broker request after expiry or a failed redemption.
Limits vary by endpoint. Institution search currently caps responses at 200 records and applies 90 requests per minute per key; other endpoint and authentication limits also apply. Do not treat a page-size limit as a throughput guarantee.
Report a problem
Include the route name, HTTP status, approximate UTC time and trace ID if returned. Redact credentials and confidential customer exports. Never send your API key in an email or screenshot. Contact Sloe.