Errors

The API uses standard HTTP status codes and returns errors in a consistent JSON envelope.

Error Response Format

{
  "ok": false,
  "error": "Invalid or expired JWT."
}

The ok field is always false on error. The error field contains a human-readable description of what went wrong.

Code	Meaning	Description
`400`	Bad Request	The request is malformed or missing required parameters. Check query parameters and request body.
`401`	Unauthorized	No valid credentials provided. The JWT is missing, expired, or malformed. Re-authenticate at id.briefedmedia.com.
`403`	Forbidden	The authenticated user does not have permission to access this resource. The JWT may lack the required `products.consumer_signals` claim, or the endpoint is restricted to a higher plan tier.
`404`	Not Found	The requested resource does not exist. Verify the endpoint path and any resource identifiers.
`429`	Too Many Requests	Rate limit exceeded on an AI-powered endpoint. Back off and retry after the duration specified in the `Retry-After` header. See Rate Limits.
`502`	Bad Gateway	An upstream service returned an invalid response. This is typically transient. Retry after a brief delay.
`503`	Service Unavailable	The service is temporarily unavailable due to maintenance or overload. Retry with exponential backoff.
`504`	Gateway Timeout	An upstream service did not respond in time. This may occur on complex AI-powered requests. Retry after a brief delay.

{
  "ok": false,
  "error": "Invalid or expired JWT."
}

{
  "ok": false,
  "error": "Insufficient permissions. Your plan does not include access to this endpoint."
}

{
  "ok": false,
  "error": "Rate limit exceeded. Retry after 45 seconds."
}

The 429 response includes the following headers:

Header	Description
`Retry-After`	Seconds to wait before retrying.
`X-RateLimit-Limit`	Maximum requests allowed in the window.
`X-RateLimit-Remaining`	Requests remaining in the current window.
`X-RateLimit-Reset`	Unix timestamp when the rate limit window resets.

{
  "ok": false,
  "error": "Service temporarily unavailable. Please retry shortly."
}