# Holidays

## GET /api/quantis/v3/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/v3/holidays/` |
| **Authentication** | `Authorization: Bearer qapi_...` |

### 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/v3/holidays/?year=2025' \
  --header 'Authorization: Bearer qapi_YOUR_KEY_HERE'

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

---

### 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.

---

### 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
    }
  }
}
```

---

### HTTP status codes

| Code | Meaning |
|---|---|
| `200 OK` | Success. |
| `400 Bad Request` | Invalid `year` or `type` parameter. |
| `401 Unauthorized` | Missing, invalid or revoked key. |
| `405 Method Not Allowed` | Only GET is supported. |
| `429 Too Many Requests` | Monthly quota spent (`quota_exceeded`) or rate limit hit (`throttled`). See [Tiers and limits](/quantis/v3/tiers-and-limits/). |
| `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 key

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

#### 429: monthly quota spent

```json
{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly quota exceeded. It resets on the 1st of next month."
  }
}
```

#### 429: rate limit hit

```json
{
  "error": {
    "code": "throttled",
    "message": "Rate limit exceeded",
    "details": {
      "retry_after": 1
    }
  }
}
```
**Note:** This endpoint is cached for **24 hours** per year + type combination.