HTTP Response Codes

The Botsi API uses standard HTTP status codes. 2xx means success, 4xx means something in your request needs changing, and 5xx means the failure was on Botsi's side.

Success#

Code	Status	Meaning
`200`	OK	The request succeeded. The body carries the requested data
`201`	Created	The request succeeded and created a resource, such as a Profile
`204`	No Content	The request succeeded with nothing to return

Client errors#

These need a change on your side before retrying. Retrying without changing anything produces the same result.

Code	Status	Meaning
`400`	Bad Request	A required parameter is missing: no `profileId`, or an empty `custom` array
`401`	Unauthorized	No valid API key in the `Authorization` header
`403`	Forbidden	The key is valid but lacks permission for that resource
`404`	Not Found	The resource does not exist
`422`	Unprocessable Entity	Well-formed but semantically wrong: a string where a number was expected
`429`	Too Many Requests	Rate limited. Slow down

429 is the one exception to "change something first": back off and retry.

Server errors#

Code	Status	Meaning
`500`	Internal Server Error	Something went wrong on Botsi's end
`502`	Bad Gateway	Invalid response from the upstream application. Retry with backoff
`503`	Service Unavailable	Temporarily overloaded or down for maintenance
`504`	Gateway Timeout	The upstream application did not respond in time. Retry with backoff

A failed Fetch Paywall should fall back, not block

Retrying a 5xx with backoff is correct for events and validation, where the data matters and arriving late is fine.

It is the wrong behavior in front of a user waiting on a Paywall. Serve your baseline variant instead. See AI Pricing Model API.

Error response format#

Errors return a JSON object with a human-readable message and a machine-readable code:

{
  "error": "Server Error.",
  "code": "internal_server_error"
}

Branch on code. It mirrors the status — bad_request, not_found, internal_server_error — so it identifies the class of failure, not the specific cause. The error string carries the detail, and is for humans reading logs rather than for branching on.