> For the complete documentation index, see [llms.txt](https://flapjax.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://flapjax.gitbook.io/docs/rest-api/guides/response-format.md).

# Response Format

Standard response envelope and status codes

Every API response uses a consistent JSON envelope with two fields: `status` and `data`.

### Response Envelope

```json
{
  "status": "<status_code>",
  "data": <response_data>
}
```

* **`status`** — A string code indicating the result of the operation.
* **`data`** — The response payload. On success, this contains the requested data (an object, array, or paginated result). On error, this is a string with a human-readable error message.

### Status Codes

| Status              | HTTP Code | Meaning                                                                      |
| ------------------- | --------- | ---------------------------------------------------------------------------- |
| `Success`           | 200       | The operation completed successfully.                                        |
| `OperationFailed`   | 500       | Something went wrong on the server (e.g., database error, record not found). |
| `FailedBindingJSON` | 400       | The request body could not be parsed as valid JSON.                          |
| `InvalidJSON`       | 400       | The JSON was valid but failed validation (e.g., missing required fields).    |
| `InvalidParameter`  | 400       | A path or query parameter is invalid (e.g., malformed record ID).            |

### Success Response Examples

**Single entity** (e.g., get a person):

```json
{
  "status": "Success",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "external_id": "user-001",
    "first_name": "Jane",
    "last_name": "Doe"
  }
}
```

**Paginated list** (e.g., list records):

```json
{
  "status": "Success",
  "data": {
    "items": [
      {
        "record_id": "64ab1234567890abcdef1234",
        "external_id": "order-001",
        "total": 99.99
      }
    ]
  }
}
```

**Create/Update** (returns the created or updated entity):

```json
{
  "status": "Success",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "external_id": "user-001",
    "first_name": "Jane"
  }
}
```

### Error Response Examples

**Invalid JSON body:**

```json
{
  "status": "FailedBindingJSON",
  "data": "invalid character '}' looking for beginning of value"
}
```

**Missing required filter:**

```json
{
  "status": "FailedBindingJSON",
  "data": "at least one filter is required"
}
```

**Record not found:**

```json
{
  "status": "OperationFailed",
  "data": "record not found"
}
```

**Invalid record ID format:**

```json
{
  "status": "InvalidParameter",
  "data": "invalid record ID"
}
```