Developer documentation
Errors, idempotency and rate limits
Build deterministic clients that recover safely and preserve diagnostic context.
Error envelope
JSON
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"request_id": "req_…"
}
}Production responses omit internal details. Quote request_id when contacting support and retain the matching X-Request-ID response header in your logs.
Status handling
| Status | Code | Client action |
|---|---|---|
| 400 | REQUEST_ERROR | Correct malformed or expired workflow input |
| 401 | INVALID_API_KEY | Refresh a user session or replace the credential |
| 403 | INSUFFICIENT_SCOPE | Do not retry; correct scope, role, status or IP policy |
| 404 | NOT_FOUND | Verify ID and tenant ownership |
| 409 | INVALID_STATE_TRANSITION | Review duplicate, idempotency or state conflict |
| 413 | REQUEST_TOO_LARGE | Split the payload within documented batch limits |
| 422 | VALIDATION_ERROR | Fix field-level input |
| 429 | RATE_LIMIT_EXCEEDED | Wait for reset with jitter |
| 500 | INTERNAL_ERROR | Retry a safe/idempotent operation with backoff and alert on persistence |
Idempotency
Idempotency-Key is required for POST /accounts, POST /accounts/bulk, POST /accounts/{account_id}/events and POST /events/bulk. Keys must be at least eight characters and are scoped to institution and endpoint.
- Generate one key for the intended business operation and persist it before sending.
- Retry the exact same body with the same key after a timeout or ambiguous transport failure.
- Reusing a key with a changed request returns 409.
- Single account and single event responses are replayed from a 24-hour idempotency record. Do not depend on indefinite retention.
Rate-limit headers
Every response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Limits apply per credential identity over minute and day windows; public write endpoints are limited to ten requests per minute.
- Throttle proactively before remaining reaches zero.
- On 429, wait until reset and add random jitter.
- Do not fan out immediate retries across workers.
- Alert on sustained throttling because it usually indicates a design or traffic anomaly.