Find the insights and best practices about our product.
Rate Limits & Error Handling

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

X-Rate-Limit-Remaining

All non-429 responses

Number of requests remaining for the current rate limit window

Retry-After

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:

  1. Stop sending requests immediately.
  2. Wait for the number of seconds specified in the Retry-After header.
  3. 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

BAD_REQUEST

A request-specific conflict, such as passing both

cursor

and

updatedAfter

on

GET /api/public/users

400/422

VALIDATION_FAILED

A malformed request (400) or a field or value that failed validation (422); check the HTTP status to tell these apart. A 422 includes

error.details

, 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

requiredPermission

. A wrong path, a wrong HTTP method or a malformed ID in the path also returns 403, not 404 or 405.

404

NOT_FOUND

The requested resource does not exist, or belongs to another tenant

409

CONFLICT

The request duplicates an existing resource, such as a duplicate email on user creation

409

VULNERABILITIES_NOT_SHARED

The vendor has not shared vulnerability data for this received AI Card. Returned only by the per-card vulnerability findings feeds.

500

INTERNAL_ERROR

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.

Did this answer your question?