Status Codes - FAQSIR

The FAQSIR API uses standard HTTP status codes to indicate the outcome of each request. This page provides a complete reference.

Success Codes

Code	Status	Description
`200`	OK	The request was successful. Used for retrieving existing sources and chat responses.
`201`	Created	A new resource was created. Returned when a new source is processed for the first time.
`202`	Accepted	The request has been accepted for asynchronous processing. Used by the Stats endpoint to acknowledge event batches.

Code	Status	Description
`401`	Unauthorized	The request lacks valid authentication credentials. Check that your `Authorization` header includes a valid Bearer token. See Authentication.
`402`	Payment Required	The site linked to your API token does not have an active subscription. Renew or upgrade your plan via the FAQSIR dashboard. See Billing.
`403`	Forbidden	The authenticated token does not have permission to access the requested resource. This can occur if you use a token from a different site.
`404`	Not Found	The requested resource does not exist. For example, requesting a source by UUID that has been deleted.
`422`	Unprocessable Entity	The request body failed validation. The response includes an `errors` object with details about which fields are invalid.
`429`	Too Many Requests	Rate limit exceeded, or a usage quota (such as the monthly source limit) has been reached. Check the `Retry-After` header and see API Limits.

Code	Status	Description
`500`	Internal Server Error	An unexpected error occurred on the server. If this persists, contact support.
`503`	Service Unavailable	The API is temporarily unavailable, typically during maintenance. The widget retries automatically with exponential backoff.

All error responses follow a consistent JSON structure:

{
  "message": "Unauthenticated."
}

Validation errors include an errors object mapping field names to arrays of error messages:

{
  "message": "The url field is required.",
  "errors": {
    "url": [
      "The url field is required."
    ]
  }
}

When a usage quota is exceeded, the response may include a helpful upgrade_url:

{
  "message": "Source limit reached. Please upgrade your plan.",
  "upgrade_url": "https://faqsir.com/billing"
}

Code	When
`200`	Existing source content returned from cache
`201`	New source created and queued for processing
`422`	Invalid URL format or missing required field
`429`	Monthly source quota exceeded

Code	When
`200`	Chat response generated successfully
`422`	Missing or invalid `message`, `session_id`, or `source_id`

Code	When
`202`	Event batch accepted for processing
`422`	Invalid events (timestamps out of range, batch too large)
`429`	Rate limit exceeded (1,200 requests/minute)