Errors

Errors use a consistent JSON shape:

{
  "error": {
    "code": "error_code",
    "message": "Human readable error",
    "requestId": "request_id"
  }
}

Common status codes

• 401 means the API key is missing, malformed, revoked, or invalid.
• 402 means an active subscription or available credits are required.
• 403 means the key is valid but missing the required scope or plan access.
• 404 means the resource is missing or inaccessible.
• 422 means validation failed after route matching.
• 429 means the request cannot be served because usage credits or limits are exhausted.
• 500 means the API failed unexpectedly.

Every response also includes X-Afterlib-Request-Id. Error responses repeat that value as error.requestId. Include the request ID when asking support to investigate a request.

Examples

Missing or invalid key:

{
  "error": {
    "code": "unauthorized",
    "message": "Missing API key",
    "requestId": "req_unauthorized"
  }
}

Subscription or credits required:

{
  "error": {
    "code": "credits_exhausted",
    "message": "Active subscription required",
    "requestId": "req_payment_required"
  }
}

Missing scope:

{
  "error": {
    "code": "forbidden",
    "message": "API key is missing ads:read scope",
    "requestId": "req_forbidden"
  }
}

Validation failure:

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request",
    "requestId": "req_validation"
  }
}

Usage limit reached:

{
  "error": {
    "code": "usage_limit_exceeded",
    "message": "Usage limit reached",
    "requestId": "req_limited"
  }
}