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 patters together to avoid exhausting the shared quota.

Rate Limit Headers

The API returns rate limit information in response headers.

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:

json

{
	"data": null,
	"pagination": null,
	"error": {
		"code": "RATE_LIMI_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 that fail authentication with a 401 Unauthorized response do not consume rate limit quota. This means failed authentication attempts do not count against your 60-requests-per-minute budget. However, 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:

json

{
  "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.

Error Codes

Handling 5xx Errors

For 5xx responses, retry the request with exponential backoff. Wait at least on 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.