# Konventionen (https://docs.otark.com/de/developer/brp-connect-api/conventions)

## Paginierung

Alle Listen-Endpunkte unterstützen Cursor-basierte Paginierung mit zwei Parametern:

| Parameter | Typ     | Beschreibung                                                                           |
| --------- | ------- | -------------------------------------------------------------------------------------- |
| `limit`   | integer | Max. Einträge pro Seite (Standard: 10, Max: 100)                                       |
| `after`   | string  | Cursor für die nächste Seite — den `next_cursor`-Wert der vorherigen Antwort übergeben |

Paginierte Antworten enthalten ein `pagination`-Objekt mit einem `next_cursor`-Feld:

```json
{
  "contracts": [ ... ],
  "pagination": {
    "limit": 10,
    "has_more": true,
    "next_cursor": "con_a1b2c3d4"
  }
}
```

Wenn `has_more` den Wert `true` hat, übergeben Sie den `next_cursor`-Wert als `after`-Parameter, um die nächste Seite abzurufen. Wenn keine weiteren Seiten vorhanden sind, ist `next_cursor` `null`.

**Beispielablauf:**

1. `GET /v1/transactions?limit=10` — gibt Einträge 1–10 zurück, `"next_cursor": "txn_abc123"`
2. `GET /v1/transactions?limit=10&after=txn_abc123` — gibt Einträge 11–20 zurück, `"next_cursor": "txn_xyz789"`
3. `GET /v1/transactions?limit=10&after=txn_xyz789` — gibt Einträge 21–25 zurück, `"has_more": false`, `"next_cursor": null`

Der Sammlungsschlüssel in der Antwort entspricht dem Ressourcennamen (z.B. `"contracts"`, `"transactions"`, `"nominations"`, `"customers"`).

## Zeitstempel

Alle Zeitstempel sind ISO 8601 in UTC:

```
2026-07-15T11:00:00Z
```

## Lieferzeiträume

Die Energielieferung verwendet die standardmäßige **PTU (Programme Time Unit)**-Konvention mit 15-Minuten-Intervallen. `delivery_date` bezeichnet den Liefertag in der Zeitzone `Europe/Berlin`; die Zeitscheiben 1–96 zählen ab 00:00 Uhr dieses lokalen Tages. Die Zeitstempel `period_from` und `period_to` stehen wie alle Zeitstempel der API in UTC:

```json
{
  "delivery_date": "2026-07-15",
  "period_from": "2026-07-15T11:00:00Z",
  "period_to": "2026-07-15T11:15:00Z"
}
```

Jeder Liefertag hat 96 Zeitscheiben von je 15 Minuten (nummeriert 1–96). Am Tag der Umstellung auf Sommerzeit sind es 92 — die Nummern 9–12 entfallen —, am Tag der Umstellung auf Winterzeit 100: Der erste Durchlauf der wiederholten Stunde behält die Nummern 9–12, der zweite trägt die Nummern 97–100 (sie entsprechen `9b` bis `12b` in den [Nominierungsdateien](https://docs.otark.com/de/developer/nomination-files)). Nach Zeitscheiben filtern die Transaktions- und Nominierungs-Endpunkte über die Parameter `slot_number_from` und `slot_number_to`.

## Fehlerantworten

Alle Fehler folgen [RFC 9457 — Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457) und werden mit `Content-Type: application/problem+json` zurückgegeben:

```json
{
  "type": "https://brp.otark.energy/errors/balance_group_tso_not_enabled",
  "title": "Balance Group TSO Not Enabled",
  "status": 400,
  "detail": "The requested TSO is not enabled for this balance group.",
  "instance": "/v1/customers/cust_r8s9t0u1"
}
```

Validierungsfehler enthalten ein `errors`-Array mit feldspezifischen Details:

```json
{
  "type": "https://brp.otark.energy/errors/validation",
  "title": "Validation Failed",
  "status": 400,
  "instance": "/v1/customers/cust_r8s9t0u1",
  "errors": [
    {
      "field": "balance_group.tso",
      "code": "invalid_enum_value",
      "message": "Invalid enum value. Expected 'DE_AMPRION' | 'DE_TENNET' | 'DE_TRANSNET_BW' | 'DE_50HERTZ'"
    }
  ]
}
```

Feldspezifische Fehlercodes: `unknown_field`, `read_only_field`, `required`, `invalid_type`, `invalid_enum_value`, `invalid_format`, `invalid_literal`, `value_too_small`, `value_too_large`, `validation_failed`.

Die API verwendet die Standard-HTTP-Statuscodes:

| Code  | Beschreibung                                                                   |
| ----- | ------------------------------------------------------------------------------ |
| `400` | Ungültige Anfrage — Validierungsfehler oder Verstoß gegen Geschäftsregeln      |
| `401` | Nicht autorisiert — fehlender oder ungültiger API-Schlüssel                    |
| `403` | Zugriff verweigert — API-Schlüssel hat nicht die erforderlichen Berechtigungen |
| `404` | Nicht gefunden — Ressource existiert nicht oder kein Zugriff                   |
| `409` | Konflikt — Operation kann im aktuellen Zustand nicht ausgeführt werden         |
| `429` | Zu viele Anfragen — Ratenlimit überschritten                                   |
| `500` | Interner Serverfehler                                                          |

## Ratenbegrenzung

Für alle APIs der Plattform gilt dieselbe Grenze: **300 Anfragen je 60-Sekunden-Fenster**. Jede Antwort enthält folgende Header:

| Header                  | Beispiel | Beschreibung                                 |
| ----------------------- | -------- | -------------------------------------------- |
| `x-ratelimit-limit`     | `300`    | Maximale Anfragen pro Fenster                |
| `x-ratelimit-remaining` | `299`    | Verbleibende Anfragen im aktuellen Fenster   |
| `x-ratelimit-reset`     | `60`     | Sekunden, bis das Fenster zurückgesetzt wird |

Bei Überschreitung des Limits gibt die API `429 Too Many Requests` zurück.
