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

# Troubleshooting

> Every error the API returns — verbatim message, cause, fix

Every rejection carries a `detail` message that names the offending part
of the request. This page lists them **verbatim**, with the fix. Test
fixes safely with [`validate_only`](/quickstart#step-2--validate-without-submitting)
— full validation, nothing stored.

## HTTP status codes

| Status | Meaning                              | What to do                                                                                                                                                   |
| ------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `401`  | Missing, wrong or expired credential | Send the key in the `X-API-Key` **header** (not the body, not a query parameter, not `Authorization` unless you use OAuth Bearer tokens)                     |
| `403`  | Valid credential, wrong scope        | The key is not entitled to this endpoint — e.g. a read-only report key on a data endpoint. Use the data-delivery key                                         |
| `413`  | Body too large                       | Split the submission (e.g. metered data into batches of days)                                                                                                |
| `422`  | Validation failure                   | Read `detail` — the exact messages are below                                                                                                                 |
| `429`  | Rate limit                           | Wait the seconds given in the `Retry-After` header, then retry                                                                                               |
| `503`  | Service restarting (deploy/scale)    | Transient by design — wait the seconds in the `Retry-After` header, then retry the identical request. Retries are safe: an identical payload changes nothing |
| `5xx`  | Service-side problem                 | Retry with backoff (502/504 from the platform edge during a restart are equally transient); if it persists, contact n:lead with the timestamp                |

## `422` on `POST /v1/forecasts`

<AccordionGroup>
  <Accordion title="series[N] has X intervals, expected 96 for 2026-09-01">
    The series does not cover the delivery day. A normal day has **96**
    quarter-hours, the spring-forward day (last Sunday of March) has
    **92**, the fall-back day (last Sunday of October) has **100**. Build
    the count from the local Europe/Berlin day — the quickstart snippets
    do this correctly.
  </Accordion>

  <Accordion title="series[N]: control area X is not in the active set">
    `control_area` must be one of `50Hertz`, `Amprion`, `TenneT`,
    `TransnetBW` — **case-sensitive**, the German TSO names, not EIC
    codes — and the area must be active for your portfolio.
  </Accordion>

  <Accordion title="series[N]: no malo_mapping entry for MaLo '…'">
    A series tagged with `malo` needs a matching entry in the request's
    `malo_mapping` object: `{"malo_mapping": {"<11 digits>": "<control area>"}}`.
  </Accordion>

  <Accordion title="Value error, exactly one of control_area or malo must be set">
    Each series carries **exactly one** tag: either `control_area` or
    `malo` — never both, never neither.
  </Accordion>

  <Accordion title="String should match pattern '^\d{11}$'">
    A market location ID (MaLo) is exactly **11 digits**, sent as a JSON
    string (leading zeros matter).
  </Accordion>

  <Accordion title="Input should be 'production' or 'consumption' / Input should be 'MW' or 'MWH'">
    `kind` takes only those two values (both series always positive — the
    bridge nets them); `unit` is `MW` (average power per quarter-hour,
    the default) or `MWH` (energy per quarter-hour).
  </Accordion>

  <Accordion title="Input should be a valid date …">
    `delivery_day` is `YYYY-MM-DD` (a Europe/Berlin calendar day), e.g.
    `"2026-09-01"` — no time component, no timezone suffix.
  </Accordion>
</AccordionGroup>

## `422` on master, metered and profile data

<AccordionGroup>
  <Accordion title="entries[N] (51238696781, 2026-08-30): X intervals, expected 96">
    Metered days follow the same quarter-hour rule as forecasts:
    96 / 92 / 100 values covering the whole local day.
  </Accordion>

  <Accordion title="entries[N] (MGA/H0, 2026-09-01): X intervals, expected 96">
    Rolled-out profile days too: one `values_kwh` entry per quarter-hour
    of the local day.
  </Accordion>

  <Accordion title="Value error, an active slice needs control_area, mga and metering_type">
    A master-data slice with `active: true` (the default) must say where
    and how the location is metered. Only a de-registration slice
    (`active: false`) may omit them.
  </Accordion>

  <Accordion title="Value error, valid_to must be after valid_from">
    Slice windows are `valid_from` (inclusive) to `valid_to` (exclusive);
    an empty or negative window is rejected.
  </Accordion>

  <Accordion title="Value error, provide either slices or the flat form with delivery_start">
    A location needs its history: either a `slices` array, or the flat
    shorthand with `delivery_start` (+ attributes) for one uninterrupted
    period.
  </Accordion>
</AccordionGroup>

## Getting `401` although the key is right?

The two attempts we see most:

1. The key sent as `Authorization: <key>` — plain keys go in the
   **`X-API-Key`** header; `Authorization: Bearer …` is only for OAuth
   tokens from a registered issuer.
2. A trailing newline or quote copied along with the key. The key is used
   byte-for-byte.

## Still stuck?

Send n:lead the **timestamp** of your call and, if you got one, the
`input_hash` from the acknowledgment — both identify your request in the
service's audit trail without you having to share the payload.