Errors, limits & retries

Read the error response

Service errors return an error object and usually request_id. HTTP ingress failures may include only error.code. Live service responses identify their mode with X-CRD-Mode: live.

Record the HTTP status, error code, and request ID when diagnosing failures. Do not log credentials, signing secrets, or authorization evidence.

{
  "error": {
    "code": "creator_not_eligible",
    "message": "The creator must have a verified mandate and active CRD entitlement."
  },
  "request_id": "req_example"
}

HTTP status codes

Common workflow errors

Preserve the logical operation

Enrollment uses your stable external ID and identical payload for reconciliation. Scan and deindex writes use the same Idempotency-Key across retries. A fresh key describes new work, not a retry.

An uncertain worker state means the service is reconciling real effects. Do not assume the operation failed or repeat it with a different identity. Read the resource and contact CRD when reconciliation is needed.

Follow each collection’s returned cursor

Use limit from 1 to 100; the default is 25. Follow next_cursor until it is null. Do not infer completion solely from an empty data array: access filtering can leave an empty page that still has a next cursor. Treat cursors as opaque values returned by that collection.

These collections reflect changing live records, not a frozen export. Deduplicate by resource ID while paging. For event polling, keep the previous saved cursor when no newer accessible event is returned, and process repeated events safely.

Retry the operation, not a new copy of the work

Scan idempotency keys are unique across the agency’s scan operations, not only within one creator. Deindex keys are unique across the agency’s deindex operations. Use a different key for each logical operation and keep scan and deindex operation records separate.

The live scan and deindex routes accept Idempotency-Key values of 1–120 characters. A matching write retry may return 200 instead of the original 201 or 202. HTTP acceptance does not mean the asynchronous work completed.

Default operating limits

These are implementation defaults, not a service-level commitment. Confirm deployment capacity and commercial limits with CRD.

Handle rate limits and transient errors

The default request allowance is 120 requests per agency API account per fixed minute, shared by all of that agency’s keys. Creating another key does not create an independent allowance. Manual scans have a separate limit of five per creator over the preceding 24 hours. Scheduled work and webhook delivery are not additional client requests you need to poll continuously.

For 429 rate_limited, pause the agency’s request queue and retry with exponential backoff and jitter. Honor Retry-After if supplied by the deployment; the live API does not guarantee that header. For 429 scan_limit_reached, wait for the creator’s rolling manual-scan allowance instead of immediately retrying.

Retry transient network failures and 502/503/504 reads with backoff. For writes, preserve the same external ID or idempotency key. Do not blindly retry 400 validation failures, 401 invalid credentials, 403 missing permissions, or 409 workflow requirements; correct the reported cause first.

Request & response example

curl --request GET 'https://api.crd.systems/v1/me' \
  --header "Authorization: Bearer $CRD_API_KEY"

{
  "partner": {
    "id": "ptn_example",
    "name": "Example Agency",
    "kind": "agency"
  },
  "workspace_id": "wsp_example",
  "key_id": "key_example",
  "scopes": [
    "workspaces:read",
    "creators:read",
    "creators:write"
  ],
  "expires_at": null,
  "environment": "live",
  "workspaces": [
    {
      "id": "wsp_example",
      "name": "Example Agency",
      "external_id": "agency_001"
    }
  ],
  "engine_configured": true
}

Illustrative response. Replace example resource IDs with the IDs returned by your API requests. View endpoint details.