Errors

Every CrystalQore API error uses the same JSON envelope, a machine-readable code, and a request ID.

Errors

Success and failure share one shape so clients can branch on success and error.code.

Envelopes

Success

{
  "success": true,
  "data": {},
  "meta": {
    "requestId": "8a1c2d3e-4f56-4789-a012-3456789abcde",
    "timestamp": "2026-10-19T17:00:00.000Z",
    "pagination": {
      "total": 12,
      "limit": 50,
      "offset": 0,
      "hasMore": false
    }
  }
}

pagination is present on list endpoints.

Error

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": []
  },
  "meta": {
    "requestId": "8a1c2d3e-4f56-4789-a012-3456789abcde",
    "timestamp": "2026-10-19T17:00:00.000Z"
  }
}

Include meta.requestId when you contact support.

HTTP status

Status	Typical codes
400	`BAD_REQUEST`, `VALIDATION_ERROR`, `MISSING_TENANT_ID`, `MISSING_USER_EMAIL`, `INVALID_DATES`, `NO_EXTENSION`, `INVALID_DESTINATION`, `TENANT_NOT_CONFIGURED`, `PBX_NOT_CONFIGURED`
401	`MISSING_API_KEY`, `INVALID_API_KEY`, `INVALID_API_KEY_FORMAT`, `UNAUTHORIZED`
402	`SUBSCRIPTION_INACTIVE` (click-to-dial)
403	`FORBIDDEN`, `PERMISSION_DENIED`, `CLIENT_DISABLED`, `TENANT_ACCESS_DENIED`, `TENANT_DISABLED`, `USER_DISABLED`, `ENTITLEMENT_REQUIRED`, `NOT_A_MEMBER`
404	`USER_NOT_FOUND`, `PARTICIPANT_NOT_FOUND`, `NOT_FOUND`
409	`PHONE_NOT_REGISTERED`, `CALL_IN_PROGRESS`
429	`RATE_LIMIT_EXCEEDED`
500	`INTERNAL_ERROR`, `CALL_FAILED`

Phone-system configuration problems use TENANT_NOT_CONFIGURED or PBX_NOT_CONFIGURED with a tenant-facing message such as “Phone system is not configured for this organization.”

Retry

429 — wait until X-RateLimit-Reset (Unix seconds) or back off and retry
5xx — retry with jitter; do not retry 409 click-to-dial or validation errors
401 / 403 — fix the key, tenant, user, or permission; retrying will not help

Errors

Errors

Envelopes

HTTP status

Retry

On this page