Error Reference

All API errors return JSON with an error field containing a machine-readable code, and an optional message field with a human-readable description.

{
  "error": "validation_error",
  "message": "creator_platforms must contain at least one entry"
}

---

HTTP status codes

Status	Code	Meaning
400	validation_error	Request body or query parameters failed validation
400	bad_request	Malformed JSON or missing required field
401	unauthorized	Missing or invalid Authorization header
403	forbidden	Valid API key but insufficient role for this endpoint
404	not_found	The requested resource does not exist
409	duplicate_request	An identical Idempotency-Key was already used for a different payload
422	unprocessable	Request is valid but cannot be executed (e.g. platform already connected)
429	rate_limited	Too many requests — see Rate Limits
500	internal_error	Unexpected server error — contact hello@creatorlayer.eu
503	service_unavailable	Temporary outage — retry with exponential backoff

---

Error details by endpoint

POST /api/v1/verifications

Error	Cause	Fix
validation_error	obligor_reference is empty or exceeds 100 characters	Trim or truncate the reference
validation_error	creator_platforms is empty or contains an unsupported platform	Use ["youtube"], ["stripe"], or ["youtube", "stripe"]
duplicate_request	Same Idempotency-Key sent with a different payload	Generate a fresh UUID per unique verification
unauthorized	Missing or malformed Authorization: Bearer header	Ensure the header is present and the key is correct

GET /api/v1/verifications/:id

Error	Cause	Fix
not_found	verification_id does not exist or belongs to another lender	Check the ID — each lender only sees their own verifications

GET /api/v1/benchmarks/:verificationId

Error	Cause	Fix
not_found	Verification is not yet completed, or ID is wrong	Poll status first; benchmarks are only available after completion

GDPR endpoints

Error	Cause	Fix
validation_error	Neither email nor obligor_id provided	Supply at least one identifier
not_found	No data found for the given identifier	The creator may already have been erased
forbidden	Endpoint requires gdpr_admin role	Request a gdpr_admin key from hello@creatorlayer.eu

---

Idempotency

POST /api/v1/verifications requires an Idempotency-Key header (UUID v4). This prevents duplicate verifications if a request is retried after a timeout.

• If the same key is resent with the same payload, the original response is returned (no new verification created).
• If the same key is resent with a different payload, a 409 duplicate_request error is returned.
• Keys expire after 24 hours — after that, the same UUID can be reused.

curl -X POST https://api.creatorlayer.eu/api/v1/verifications \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

---

Retrying errors

Status	Retry?	Strategy
400, 401, 403, 404, 409, 422	No	Fix the request — retrying will return the same error
429	Yes	Wait for the Retry-After header value (seconds), then retry
500	Yes	Retry once after 5 seconds; if it persists, contact support
503	Yes	Exponential backoff: 1s → 2s → 4s → 8s (max 3 retries)