Skip to main content

Error Codes

Response envelope​

Every response from the CMP public API — success or failure — is wrapped in the same envelope:

{
"entity": { /* the actual data, or null on failure */ },
"warnings": [],
"errors": [
{ "message": "Human-readable message", "code": 18000, "status": false }
],
"success": true
}

Check success (or equivalently, whether errors is non-empty) rather than only relying on the HTTP status code — errors[0].message is the string you should surface to a developer/log, and errors[0].code is the stable identifier to branch your handling logic on.

Authentication failures (no envelope)​

Requests that fail authentication before reaching application logic don't get the envelope above — they return a bare response with no JSON body to parse:

  • 401 Unauthorized — the X-Org-Api-Key header is missing, doesn't match any known key, or matches a revoked key; or a principal-scoped endpoint (see the 🔒 markers in the API Reference) was called with a missing, invalid, or expired X-Principal-Token.
  • 403 Forbidden — a Publishable key was used against a server-to-server endpoint (/api/v1/server/cmp/*), which requires a Secret key. See Authentication → Publishable vs. Secret keys.

See Authentication for the full credential model.

CMP status codes​

CodeNameMeaningTypically seen from
18000CMP_GENERAL_ERRORAn unexpected error, or a business-rule violation without its own dedicated code (e.g. "notice not found", "purposes can only be added to DRAFT notices", "minor consent without a registered guardian")Any endpoint
18001CMP_INVALID_ORGThe resolved org doesn't match what's expected for this requestInternal — rare on the public API
18002CMP_NOTICE_NOT_FOUNDNo ACTIVE notice exists for the requested groupKey/languageGET /notice
18003CMP_NOTICE_DRAFT_ONLYAttempted an operation only valid on a DRAFT noticeAdmin API only — not reachable from the public API
18004CMP_API_KEY_REVOKE_FAILEDFailed to revoke an API keyAdmin API only
18005CMP_PRINCIPAL_REGISTRATION_FAILEDPrincipal registration failedPOST /principals/register
18006CMP_PRINCIPAL_TOKEN_FAILEDToken issuance failed (e.g. unknown externalId)POST /principals/token
18009CMP_GUARDIAN_MISSINGConsent grant attempted for a minor with no guardian registered at allPOST /consent/grant
18010CMP_GUARDIAN_NOT_VERIFIEDConsent grant attempted for a minor whose guardian record exists but isn't MANUALLY_VERIFIED (still UNVERIFIED, or REJECTED)POST /consent/grant
Most failures currently surface as 18000

Many specific failure conditions (invalid notice ID on grant, malformed purpose selections) currently come back as the general 18000 code with a descriptive message rather than their own dedicated code. Match on the message string during development, and treat 18000 as "read the message" rather than a single specific condition. The two minor/guardian-related grant failures are the exception — see 18009/18010 above, which are stable identifiers you can branch on directly. Dedicated codes may be added over time for more of these — this page will be updated when they are.

HTTP status codes​

StatusMeaning
200 OKSuccessful read
201 CreatedSuccessful creation (registration, consent grant, DSR/grievance submission)
400 Bad RequestThe request was rejected due to invalid input or a business rule (check the envelope's errors)
401 UnauthorizedMissing, invalid, or revoked X-Org-Api-Key, or missing/invalid/expired X-Principal-Token on an endpoint that requires one
403 ForbiddenA Publishable key was used against a Secret-key-only, server-to-server endpoint
404 Not FoundThe requested resource (e.g. active notice, DSR/grievance reference) doesn't exist — or exists but belongs to a different principal than your X-Principal-Token identifies
500 Internal Server ErrorAn error occurred processing an otherwise-valid, authenticated request — still returns the structured envelope; check errors[0].message

Yes, some failure conditions return 500 rather than 400/404 even though they're really "your request was invalid" (e.g. granting consent against a nonexistent noticeId) — the envelope's success: false and errors[0] are the reliable signal, more so than the HTTP status alone. Always check both, but treat the envelope as authoritative.