API Foutmeldingen

Deze pagina beschrijft hoe onze API foutmeldingen teruggeeft, welke HTTP‑statuscodes we gebruiken, en hoe de JSON‑structuur eruitziet.

TL;DR

• Alle fouten volgen het Google JSON error patroon.

• Body:

  {
    "id": "<request-id>",
    "status": "failure",
    "error": {
      "code": <http-status-code>,
      "message": "<korte samenvatting>",
      "errors": [
        { "reason": "<machine-leesb. reden>", "message": "<menselijke uitleg>" }
      ]
    }
  }

• CORS‑headers zijn aanwezig op alle foutantwoorden.

• Waar van toepassing geven we extra context via errors[].reason.

---

Standaard JSON‑structuur

{
  "id": "<request-id>",
  "status": "failure",
  "error": {
    "code": 404,
    "message": "Not Found",
    "errors": [
      {
        "reason": "Not Found",
        "message": "The requested route or method was not found."
      }
    ]
  }
}

Velden

• error.code (number): De HTTP‑statuscode.

• error.message (string): Korte samenvatting (in het Engels; stabiele API‑conventie).

• error.errors (array): Optionele lijst met detailobjecten:

  • reason (string): Machine‑leesbare reden (stabiele sleutel die clients kunnen mappen).

  • message (string): Menselijke toelichting; kan in de loop der tijd verfijnen.

---

Scenario’s & statuscodes

400 — Bad Request

Wordt teruggegeven wanneer parameters onjuist zijn ingegeven.

Voorbeelden van oorzaken

• Verplichte parameter ontbreekt.

• Waarde van een parameter is onjuist.

Response

{
  "id": "<request-id>",
  "status": "failure",
  "error": {
    "code": 400,
    "errors": [
      {
        "reason": "postalCode",
        "message": "this value must be of format 1234AB"
      },
      {
        "reason": "houseNumber",
        "message": "Field required"
      },
      {
        "reason": "buildYear",
        "message": "Input should be a valid integer, unable to parse string as an integer"
      }
    ],
    "message": "Bad Request"
  }
}

401 — Unauthorized

Wordt teruggegeven wanneer authenticatie ontbreekt of ongeldig is.

Voorbeelden van oorzaken

• Verkeerde of ontbrekende Authorization: Bearer <api-key> header.

• Inactieve API‑key.

Response

{
  "id": "<request-id>",
  "status": "failure",
  "error": { "code": 401, "message": "Unauthorized", "errors": [] }
}

---

403 — Forbidden

Wordt teruggegeven wanneer de aanroepende klant bekend is, maar geen rechten heeft op de gevraagde resource.

Mogelijke reasons

• access_denied — algemene weigering.

• missing_subscription — endpoint valt buiten het abonnement.

• rate_limit — als throttling wordt afgedwongen (dan blijft het statuscode 403).

Response

{
  "id": "<request-id>",
  "status": "failure",
  "error": {
    "code": 403,
    "message": "Forbidden",
    "errors": [
      { "reason": "missing_subscription", "message": "Your plan does not include access to this endpoint." }
    ]
  }
}

{
  "id": "<request-id>",
  "status": "failure",
  "error": {
    "code": 403,
    "message": "Forbidden",
    "errors": [
      { "reason": "rate_limit", "message": "Rate limit exceeded. Please retry later." }
    ]
  }
}

Voordat u live gaat met uw oplossing en hogere volume API calls wilt maken, neem dan contact met ons op (via [email protected]) om de rate-limits te verhogen.

---

404 — Not Found

We gebruiken 404 in twee situaties:

1. Route/methode bestaat niet (bijv. /v1/niet-bestaand).

2. Resource bestaat niet (bijv. object‑ID onbekend, onbekend adres).

Responses

{
  "id": "<request-id>",
  "status": "failure",
  "error": {
    "code": 404,
    "message": "Not Found",
    "errors": [ { "reason": "Not Found", "message": "The requested route or method was not found." } ]
  }
}

{
  "id": "<request-id>",
  "status": "failure",
  "error": {
    "code": 404,
    "message": "Not Found",
    "errors": [ { "reason": "Not Found", "message": "The requested resource does not exist." } ]
  }
}

---

CORS

Alle foutantwoorden bevatten CORS‑headers:

Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *
Access-Control-Allow-Methods: *

Richtlijnen voor clients

• Gebruik error.code voor primaire afhandeling (HTTP‑niveau).

• Gebruik errors[0].reason voor specifieke beslissingen

• Log de id , uit de body, en de header X-Amzn-Trace-Id voor support/correlatie.

---

Backwards compatibility

Het top‑level error‑object en de waarden van error.code en error.message blijven stabiel. We kunnen nieuwe reason‑waarden toevoegen; clients dienen onbekende reasons te negeren of als generieke fout te behandelen.

---

Contact & support

Neem bij vragen of onduidelijkheden contact op via onze support ([email protected]). Vermeld altijd de endpoint‑URL, timestamp, en (indien mogelijk) de id en de X-Amzn-Trace-Id.