> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/api/en/preparation/status-code.md).
# Status Codes
This guide introduces the HTTP status codes returned when integrating with MaiAgent services through the API, with examples of response formats
When sending HTTP requests through the API, use the following status codes to determine whether a request succeeded:
## Status code descriptions
### Success codes
| Status code | Description |
| ----------- | -------------------------------------------------------------- |
| 200 | Request succeeded |
| 201 | Resource created successfully |
| 204 | Request succeeded with no response body (common for deletions) |
#### Successful response example
{% hint style="info" %}
This is an example only. Response formats may vary by endpoint; refer to the documentation for the specific endpoint.
{% endhint %}
```json
{
"count": "integer",
"next": "string|null",
"previous": "string|null",
"results": [
// Returned result content
]
}
```
### Error codes
| Status code | Description |
| ----------- | ---------------------------------------------------------------------------- |
| 400 | Invalid request format |
| 401 | Authentication failed |
| 402 | Plan, Credits, or quota insufficient; see [402 responses](#payment-required) |
| 403 | Insufficient permissions |
| 404 | Resource does not exist |
| 409 | Conflict with the resource's current state; see [409 responses](#conflict) |
| 429 | Rate limit exceeded; see [429 responses](#too-many-requests) |
| 500 | Server error |
{% hint style="info" %}
Error responses primarily take three forms: a `detail` object (such as `{"detail": "…"}`, sometimes with a `code`), a field object (with camelCase field names as keys), or an array of strings. AI Gateway's OpenAI-compatible endpoints use an OpenAI-format `error` object. Handle errors based on the status code and `code`, rather than matching the `detail` text. For full descriptions and handling recommendations, see [API Conventions: Error Responses](/api/en/preparation/conventions.md#errors).
{% endhint %}
#### Error response examples
#### 400 - Bad request: missing required fields
```javascript
{
"files": ["This field is required."],
"filename": ["This field is required."],
"file": ["This field is required."]
}
```
#### 402 - Insufficient plan, Credits, or quota
`402` covers three cases. Only “no active paid plan” includes a `code`:
| Case | `code` |
| ----------------------------------------------------------------------------------------- | ---------------- |
| The organization has no active paid plan | `no_active_plan` |
| The organization has insufficient Credits | None |
| A member's personal quota is exhausted or unallocated, or their role's quota is exhausted | None |
```json
{
"detail": "Your organization has no active paid plan. Please upgrade to continue using the platform.",
"code": "no_active_plan"
}
```
```json
{
"detail": "Insufficient credits for KB search. Please top up your account."
}
```
Responses for insufficient Credits and exhausted quotas contain only `detail`, whose text varies by endpoint and language. You cannot distinguish these cases from the response body; ask an organization administrator to check the admin console. AI Gateway endpoints use a different format; see [API Conventions: 402](/api/en/preparation/conventions.md#payment-required).
#### 409 - Conflict with the resource's current state
The request conflicts with the resource's current state, such as when the same job is already running or a resource to be deleted is still referenced by other resources. The response is a `detail` object, and some endpoints include additional fields needed to handle the error:
```json
{
"detail": "An FAQ import is already running for this knowledge base.",
"jobId": "…"
}
```
Retrieve the resource's latest state before deciding what to do next. Do not resend the request unchanged.
#### 429 - Rate limit exceeded
Exceeding the API key's requests per minute (RPM) or an endpoint's fixed limit returns `429` with a `Retry-After` header (in seconds):
```json
{
"detail": "Request was throttled. Expected available in 42 seconds."
}
```
Wait for the number of seconds specified in `Retry-After` before retrying; do not resend immediately. For the scope of rate limiting, see [API Conventions: Rate Limits](/api/en/preparation/conventions.md#rate-limits).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.maiagent.ai/api/en/preparation/status-code.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.