Skip to main content
Errors follow RFC 9457 Problem Details, served with the media type application/problem+json. Branch on the HTTP status for flow control and on the code field for specifics.

​
Error shape

{
  "type": "urn:creatoraudit:error:not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Account not found.",
  "code": "NOT_FOUND",
  "instance": "/v2/accounts/{id}",
  "request_id": "8f1c2a4e-…"
}
​
type
string
An RFC 9457 URN identifying the error class (urn:creatoraudit:error:…).
​
title
string
Short, human-readable summary of the error class.
​
status
integer
The HTTP status code, repeated in the body.
​
detail
string
Human-readable explanation specific to this occurrence.
​
code
string
Stable, machine-readable identifier (for example, NOT_FOUND). Branch on this.
​
instance
string
The path of the request that failed.
​
request_id
string
Correlation ID for this request, mirroring the X-Request-ID response header.

​
Validation errors

A 422 (code: VALIDATION_ERROR) additionally carries an errors array describing each field that failed validation (an example entry is shown below): 
{
  "type": "urn:creatoraudit:error:validation-error",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Request failed validation.",
  "code": "VALIDATION_ERROR",
  "instance": "/v2/accounts",
  "request_id": "3b9d…",
  "errors": [{ "field": "platform", "message": "must be one of: instagram, tiktok" }]
}

​
Status codes

HTTPcodeMeaning
400BAD_REQUESTMalformed request.
401UNAUTHORIZEDMissing or invalid API key.
403FORBIDDENInactive key or subscription.
403INSUFFICIENT_SCOPEKey lacks the required scope.
403QUOTA_EXCEEDEDAccount quota reached.
404NOT_FOUNDResource not found in your organization.
406NOT_ACCEPTABLEAccept header not satisfiable as JSON.
409CONFLICTState conflict (for example, a duplicate).
415UNSUPPORTED_MEDIA_TYPEWrite body is not JSON.
422VALIDATION_ERRORRequest failed validation.
429RATE_LIMITEDRate limit exceeded.
500INTERNAL_ERRORUnexpected server error.
502UPSTREAM_ERRORUpstream provider error.
503SERVICE_UNAVAILABLETemporarily unavailable; retry.
Authentication-specific statuses are covered in Authentication; 429 handling and back-off live in Rate limits.

​
Handle errors robustly

  • Branch on status, then code. Use the HTTP status for coarse flow (retry, reauthenticate, surface to the user) and code for precise handling — for example, distinguishing INSUFFICIENT_SCOPE from QUOTA_EXCEEDED within 403.
  • Read errors on 422. Map each { field, message } back to the input that caused it.
  • Always capture X-Request-ID. Log it (or the request_id body field) with every failure so support can correlate a call to its server-side event.
  • Retry the right ones. Retry 429 and 503 with back-off and honor Retry-After; do not blindly retry 4xx validation or auth errors — fix the request instead.
  • Parse defensively. Treat any non-2xx as a problem document and read code rather than string-matching on detail.
import httpx

resp = httpx.get(url, headers=headers)
if resp.is_error:
    problem = resp.json()
    request_id = resp.headers.get("X-Request-ID")
    raise RuntimeError(
        f"{resp.status_code} {problem['code']}: {problem['detail']} "
        f"(request_id={request_id})"
    )
If you hit an unexpected 5xx, include the X-Request-ID when you contact support@creatoraudit.com.