The Cranium Public REST API enforces per-customer rate limits and returns standardized error responses when requests fail. This article covers the rate limit thresholds, the headers and response bodies returned for rate limit and error conditions, and recommended client behavior.
Rate Limits
The Public API allows up to 60 requests per minute per customer across all users and integrations within an organization. The limit is enforced on a fixed-window basis, meaning all requests count against the same minute-aligned window.
All users, integrations, and credential sets within a single Cranium tenant share the same quota. If your organization runs multiple integrations against the API, plan their request patterns together to avoid exhausting the shared quota.
Rate Limit Headers
The API returns rate limit information in response headers.
Header | Returned on | Description |
|---|---|---|
| All non-429 responses | Number of requests remaining for the current rate limit window |
| 429 responses | Number of seconds to wait before retrying |
Use these headers to pace your client. If X-Rate-Limit-Remaining is approaching zero, slow down outbound requests until the next window begins.
429 Too Many Requests
When a request exceeds the rate limit, the API returns a 429 response.
Response status: 429 Too Many Requests
Response headers:
Retry-After: 30
Response body:
{"data": null,"pagination": null,"error": {"code": "RATE_LIMIT_EXCEEDED","message": "Rate limit is exceeded. Try again in 30 seconds.","traceId": "0HMV8K3PQRSN9:00000042"},"meta": {"requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6","timestamp": "2026-08-13T10:00:00Z"}}
The Retry-After value indicates how many seconds your client should wait before retrying. Always honor this value rather than retrying immediately.
Recommended Client Behavior
When you receive a 429 response:
- Stop sending requests immediately.
- Wait for the number of seconds specified in the
Retry-Afterheader. - Retry the request once the wait period has elapsed.
If your client makes many requests in quick succession, consider adding a small delay between requests to keep X-Rate-Limit-Remaining from approaching zero. For high-volume use cases, batch operations into off-peak hours where possible.
Authentication Errors & Quota
Requests rejected because the token is missing, invalid or expired receive 401 Unauthorized and do not consume rate limit quota. Every request with a valid token counts against the 60-requests-per-minute budget, whatever it returns. This includes a 403 for a missing permission, a 409 and a 503. A client that keeps retrying a 403 uses up quota that all of the tenant's API clients share.
Repeated authentication failures may trigger other security measures. Resolve authentication issues promptly rather than retrying with invalid credentials.
Error Responses
The Public API returns standard HTTP status codes. Error responses include a JSON body describing the error.
Common error response format:
{"data": null,"pagination": null,"error": {"code": "VALIDATION_FAILED","message": "Validation failed.","traceId": "0HMV8K3PQRSN9:00000014","details": [{ "field": "name", "message": "Name is required." }]},"meta": {"requestId": "2a8b3c4d-1e5f-4a6b-bc7d-8e9f0a1b2c3d","timestamp": "2026-08-13T10:00:01Z"}}
When a request body fails validation, the API returns 422 with the code VALIDATION_FAILED. The message is always "Validation failed." The details array lists each failed rule as a { field, message } object, with the field named as it appears in your request body, so you can correct every problem in one round trip. A field can appear more than once if it fails more than one rule. Other errors don't include details.
Most errors use the format above. A 403 or a 503 does not. The API rejects these requests before they reach the endpoint, so the body is a smaller body with content type application/problem+json. It has title, status and detail, and no error, meta or requestId. A 401 has an empty body.
Error Codes
Status | Code | Typical cause |
|---|---|---|
400 |
| A request-specific conflict, such as passing both
and
on
|
400/422 |
| A malformed request (400) or a field or value that failed validation (422); check the HTTP status to tell these apart. A 422 includes
, which names each failing field. |
401 | (empty body) | The token is missing, invalid or expired. Request a new token and retry. |
403 | (no code; see Permission Errors) | The API client's role lacks the permission the request needs, or your tenant is not licensed for the feature. The body names the permission in
. A wrong path, a wrong HTTP method or a malformed ID in the path also returns 403, not 404 or 405. |
404 |
| The requested resource does not exist, or belongs to another tenant |
409 |
| The request duplicates an existing resource, such as a duplicate email on user creation |
409 |
| The vendor has not shared vulnerability data for this received AI Card. Returned only by the per-card vulnerability findings feeds. |
500 |
| An unexpected server error |
503 | (no code; small body) | Permissions could not be verified. The request did not fail on its merits. Retry it after a short wait. |
Permission Errors (403)
A 403 means the request reached the API with a valid token but was not permitted. Requesting a new token does not help, because a new token has the same permissions.
When the API client's role lacks a permission, the body names it:
{"title": "Forbidden","status": 403,"detail": "You don't have the Api_Vulnerabilities_Read permission needed for this request. Ask an administrator to grant it.","requiredPermission": "Api_Vulnerabilities_Read"}
Grant the permission named in requiredPermission to the API client's role, then retry. Retrying without the grant cannot succeed.
A wrong path, a wrong HTTP method or a malformed ID in the path returns 403 with the detail "This endpoint does not permit the request." and no requiredPermission. Check the path and method before the role.
Handling 5xx Errors
For 5xx responses, including a 503 when permissions could not be verified, retry the request with exponential backoff. Wait at least one second before the first retry, doubling the delay on each subsequent retry up to a reasonable maximum (for example, 60 seconds). Stop retrying after a small number of attempts and surface the error to your monitoring system.
When reporting persistent issues to Cranium support, include the meta.requestId or error.traceId value from the failing response; they refer to the same request. This identifier helps engineering correlate logs across the request lifecycle. A 503 response has no meta.requestId or error.traceId. For a 503, note the time of the request and the endpoint you called, and include them in your report.





