# Holidays

sidebar:
  order: 20

## GET /api/quantis/v2/holidays/

Returns the list of Venezuelan bank and public holidays for a given year, with context about whether today is a holiday.

| | |
|---|---|
| **Method** | `GET` |
| **URL** | `https://app.vzla.io/api/quantis/v2/holidays/` |
| **Authentication** | `Authorization: Bearer vzlaio_...` |

### Query parameters

| Parameter | Type | Required | Description | Default |
|---|---|---|---|---|
| `year` | integer | No | The calendar year to query, e.g. `2025` | Current year |
| `type` | string | No | Filter by type: `bancario` (banking) or `feriado` (public) | All types |

### Request

```bash
# All holidays for 2025
curl --request GET \
  --url 'https://app.vzla.io/api/quantis/v2/holidays/?year=2025' \
  --header 'Authorization: Bearer vzlaio_YOUR_TOKEN_HERE'

# Banking holidays only
curl --request GET \
  --url 'https://app.vzla.io/api/quantis/v2/holidays/?year=2025&type=bancario' \
  --header 'Authorization: Bearer vzlaio_YOUR_TOKEN_HERE'
```

---
sidebar:
  order: 20

### Response

#### `data`

A flat array of holiday objects.

| Field | Type | Description |
|---|---|---|
| `date` | string (ISO 8601 date) | Holiday date, e.g. `"2025-01-01"` |
| `name` | string | Holiday name |
| `type` | string | `"bancario"` or `"feriado"` |
| `notes` | string | Optional notes about this holiday |

#### `meta`

| Field | Type | Description |
|---|---|---|
| `today` | object | Context about the current calendar day |

**`meta.today`**

| Field | Type | Description |
|---|---|---|
| `date` | string (ISO 8601 date) | Today's date |
| `is_bank_holiday` | boolean | Whether today is a bank holiday |
| `is_weekend` | boolean | Whether today is Saturday or Sunday |

`meta.today` always reflects the current day, regardless of which `year` you queried.

---
sidebar:
  order: 20

### Response headers

| Header | Description |
|---|---|
| `X-API-Version` | `2.0` |
| `X-Quota-Limit` | Your monthly request limit |
| `X-Quota-Remaining` | Requests remaining this month |
| `X-Quota-Reset` | ISO 8601 timestamp of next quota reset |
| `X-Request-ID` | UUID for this request |

---
sidebar:
  order: 20

### Example response

```json
{
  "data": [
    {
      "date": "2025-01-01",
      "name": "Año Nuevo",
      "type": "bancario",
      "notes": ""
    },
    {
      "date": "2025-05-12",
      "name": "Día del Trabajador",
      "type": "feriado",
      "notes": ""
    },
    {
      "date": "2025-06-03",
      "name": "Día de la Independencia",
      "type": "bancario",
      "notes": ""
    },
    {
      "date": "2025-11-04",
      "name": "Día de la Resistencia Indígena",
      "type": "bancario",
      "notes": ""
    },
    {
      "date": "2025-11-12",
      "name": "Día de la Raza",
      "type": "feriado",
      "notes": ""
    }
  ],
  "meta": {
    "today": {
      "date": "2026-05-06",
      "is_bank_holiday": false,
      "is_weekend": false
    }
  }
}
```

---
sidebar:
  order: 20

### HTTP status codes

| Code | Meaning |
|---|---|
| `200 OK` | Success. |
| `400 Bad Request` | Invalid `year` or `type` parameter. |
| `401 Unauthorized` | Missing or invalid token. |
| `405 Method Not Allowed` | Only GET is supported. |
| `429 Too Many Requests` | Monthly quota exhausted. |
| `500 Internal Server Error` | Server error. Retry after a short delay. |

#### 400 — invalid year

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "year must be a 4-digit integer",
    "details": {}
  }
}
```

#### 400 — invalid type

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "type must be one of: bancario, feriado",
    "details": {}
  }
}
```

#### 401 — no Authorization header

```json
{
  "error": {
    "code": "auth_missing",
    "message": "Authentication credentials were not provided"
  }
}
```

#### 401 — invalid token

```json
{
  "error": {
    "code": "auth_token_unknown",
    "message": "Invalid token format"
  }
}
```

#### 429

```json
{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly quota limit exceeded.",
    "details": {
      "reset_at": "2026-06-01T00:00:00Z"
    }
  }
}
```
**Note:** This endpoint is cached for **24 hours** per year + type combination.