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— theX-Org-Api-Keyheader 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 expiredX-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
| Code | Name | Meaning | Typically seen from |
|---|---|---|---|
18000 | CMP_GENERAL_ERROR | An 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 |
18001 | CMP_INVALID_ORG | The resolved org doesn't match what's expected for this request | Internal — rare on the public API |
18002 | CMP_NOTICE_NOT_FOUND | No ACTIVE notice exists for the requested groupKey/language | GET /notice |
18003 | CMP_NOTICE_DRAFT_ONLY | Attempted an operation only valid on a DRAFT notice | Admin API only — not reachable from the public API |
18004 | CMP_API_KEY_REVOKE_FAILED | Failed to revoke an API key | Admin API only |
18005 | CMP_PRINCIPAL_REGISTRATION_FAILED | Principal registration failed | POST /principals/register |
18006 | CMP_PRINCIPAL_TOKEN_FAILED | Token issuance failed (e.g. unknown externalId) | POST /principals/token |
18009 | CMP_GUARDIAN_MISSING | Consent grant attempted for a minor with no guardian registered at all | POST /consent/grant |
18010 | CMP_GUARDIAN_NOT_VERIFIED | Consent grant attempted for a minor whose guardian record exists but isn't MANUALLY_VERIFIED (still UNVERIFIED, or REJECTED) | POST /consent/grant |
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
| Status | Meaning |
|---|---|
200 OK | Successful read |
201 Created | Successful creation (registration, consent grant, DSR/grievance submission) |
400 Bad Request | The request was rejected due to invalid input or a business rule (check the envelope's errors) |
401 Unauthorized | Missing, invalid, or revoked X-Org-Api-Key, or missing/invalid/expired X-Principal-Token on an endpoint that requires one |
403 Forbidden | A Publishable key was used against a Secret-key-only, server-to-server endpoint |
404 Not Found | The 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 Error | An 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.