# API Error Codes

## HTTP Response Codes

* Response codes **2XX** indicate a successfully processed request (e.g., code 200 for retrieving data, code 201 for adding a new entity, code 204 for deletion, etc.).
* Response codes **4XX** indicate that a request could not be processed correctly because of some client-side data issues (e.g., 404 when addressing a non-existing resource).
* Response codes **5XX** indicate that an internal server-side error occurred during the request processing (e.g., when database is temporarily unavailable).

## Response Body with Errors

Each response error includes HTTP code and JSON data with error description. It has the following structure:

* `error_code` – integer error code;
* `error_message`– text error description;
* `details` – additional error details (format is specified to each case). Can be empty.

Sample error response:

```javascript
{
    "error_code": 0,
    "error_message": "Unknown server side error occurred",
    "details": null
}
```

Error codes:

* `0 – UNKNOWN` Unknown server error.
* `1 - NOT ALLOWED` An unallowed method is called. Usually is followed by the 405 HTTP status of response. For example, trying to request the PATCH method, while only GET/POST ones are supported.
* `2 - NOT REALIZED` The method is documented but is not realized by any temporary or permanent reason.
* `3 - INVALID STRUCTURE` Incorrect structure of request. Some required fields missing or a format validation error occurred.
* `4 - INVALID VALUE` Incorrect value of the parameter inside request body or query.
* `5 - INVALID TYPE` The invalid data type of the request parameter.
* `6 - AUTH NOT PROVIDED` Access token not specified.
* `7 - AUTH INVALID` The access token does not exist in the database.
* `8 - AUTH EXPIRED` Auth token is expired.
* `9 - AUTH FORBIDDEN` Access denied for the current user.
* `10 - NOT EXIST` the requested resource is not found (alternative of HTTP status\_code = 404).
* `11 - EXTERNAL SERVICE` Error in the external information system.
* `12 – DATABASE` Critical database error on the server host.

### OzCapsula Errors

| **Error code** | **Error message**                                                                                                                                                      | **Description**                                                         |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| 3              | Invalid structure                                                                                                                                                      | Missing payload.json                                                    |
| 4              | Can't start analysis without media                                                                                                                                     | No media have been added into container                                 |
| 5              | Invalid Type                                                                                                                                                           | Container is damaged                                                    |
| 13             | No data container provided                                                                                                                                             | API didn’t receive the container                                        |
| 14             | <ul><li>Data container unpacking failed</li><li>Invalid Data Container</li><li>Invalid signature</li><li>Invalid hash</li><li>Invalid or empty Session Token</li></ul> | The container appears to be affected by errors and can’t be unpackaged. |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.ozforensics.com/oz-knowledge/guides/developer-guide/api/oz-api/http-return-codes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.