Errors

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-…"
}

string

An RFC 9457 URN identifying the error class (urn:creatoraudit:error:…).

string

Short, human-readable summary of the error class.

integer

The HTTP status code, repeated in the body.

string

Human-readable explanation specific to this occurrence.

string

Stable, machine-readable identifier (for example, NOT_FOUND). Branch on this.

string

The path of the request that failed.

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

HTTP	`code`	Meaning
400	`BAD_REQUEST`	Malformed request.
401	`UNAUTHORIZED`	Missing or invalid API key.
403	`FORBIDDEN`	Inactive key or subscription.
403	`INSUFFICIENT_SCOPE`	Key lacks the required scope.
403	`QUOTA_EXCEEDED`	Account quota reached.
404	`NOT_FOUND`	Resource not found in your organization.
406	`NOT_ACCEPTABLE`	`Accept` header not satisfiable as JSON.
409	`CONFLICT`	State conflict (for example, a duplicate).
415	`UNSUPPORTED_MEDIA_TYPE`	Write body is not JSON.
422	`VALIDATION_ERROR`	Request failed validation.
429	`RATE_LIMITED`	Rate limit exceeded.
500	`INTERNAL_ERROR`	Unexpected server error.
502	`UPSTREAM_ERROR`	Upstream provider error.
503	`SERVICE_UNAVAILABLE`	Temporarily 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.

Conventions

Accounts

Videos

Creators

Analytics

Overview

Search

System

Error shape

Validation errors

Status codes

Handle errors robustly

​Error shape

​Validation errors

​Status codes

​Handle errors robustly

Error shape

Validation errors

Status codes

Handle errors robustly