> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hudhud.sa/llms.txt
> Use this file to discover all available pages before exploring further.

# Response Format

> Understanding the standard JSON envelope and error handling.

All Hudhud APIs return a consistent JSON envelope to make parsing easy across different programming languages.

## Standard Envelope

Most Hudhud APIs (Geocoding, Routing) wrap their results in a standard envelope to provide consistent status and error reporting:

```json theme={null}
{
  "ok": true,
  "data": { ... },
  "error": null
}
```

| Field   | Type      | Description                                               |
| :------ | :-------- | :-------------------------------------------------------- |
| `ok`    | `boolean` | `true` if the request succeeded, `false` if it failed.    |
| `data`  | `object`  | The actual results (present only on success).             |
| `error` | `string`  | A human-readable error message (present only on failure). |

## Exceptions: Maps Styles

The **Get Map Styles** endpoint is an exception. To ensure full compatibility with map rendering libraries, it returns a **raw MapLibre GL Style JSON** object directly, without the `{ ok, data, error }` wrapper.

```json theme={null}
{
  "version": 8,
  "name": "Hudhud Light",
  "sources": { ... },
  "layers": [ ... ]
}
```

## Error Codes

Hudhud uses standard HTTP status codes to indicate the success or failure of an API request.

| Status | Description                                                                     |
| :----- | :------------------------------------------------------------------------------ |
| `200`  | **Success**: The request worked as expected.                                    |
| `400`  | **Bad Request**: Usually missing parameters or invalid coordinates.             |
| `401`  | **Unauthorized**: Invalid or missing API key.                                   |
| `403`  | **Forbidden**: The API key does not have permission for this specific service.  |
| `404`  | **Not Found**: The requested resource (map ID, shortcode, etc.) does not exist. |
| `500`  | **Server Error**: Something went wrong on our end.                              |

## Content Type

Ensure your requests include the following header:

```http theme={null}
Content-Type: application/json
```