Foutcodes

Elke fout is application/problem+json (RFC 9457). De code is het contract: hij verandert niet, ook niet als de tekst van title of detail verandert. Programmeer op code, nooit op title.

{
  "type": "https://cargofollow.com/errors/validation_failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "The body does not match the schema.",
  "code": "validation_failed",
  "request_id": "req_01M2FP3S65WEANPZF49VGJRATH",
  "errors": [{ "path": "goods.0.gross_weight_kg", "message": "Expected number, received string" }],
  "warnings": []
}

• code — de stabiele foutcode uit de tabel hieronder.
• request_id — noem dit nummer bij support; ermee vinden we jouw exacte verzoek terug.
• errors — per veld wat er mis is, bij validation_failed en regelbevindingen.
• warnings — bevindingen die het verzoek niet blokkeerden.
• title — Engels standaard, vertaald als je Accept-Language: nl meestuurt.

Alle codes

De tabel komt uit het register in @freightapi/core/errors; wat de API kan teruggeven staat hier, en niets anders.

Code	Status	Betekenis
bad_request	400	Bad request Het verzoek klopt niet: een verkeerde parameter, een ontbrekende header of een combinatie die niet bestaat.
invalid_cursor	400	Invalid cursor De meegegeven `cursor` komt niet uit een eerdere lijstrespons of is verlopen. Begin de lijst opnieuw zonder cursor.
invalid_id	400	Invalid identifier Een identifier in het pad of de body heeft niet de verwachte vorm.
malformed_json	400	Malformed JSON body De body is geen geldige JSON. Controleer content-type en encoding.
invalid_api_key	401	Invalid API key De API-key bestaat niet, is ingetrokken of hoort bij een andere omgeving.
unauthorized	401	Authentication required Er is geen API-key meegestuurd. Zet hem in de `Authorization: Bearer`-header.
forbidden	403	Forbidden De key is geldig, maar mag deze resource niet zien of wijzigen.
insufficient_scope	403	Insufficient scope De key mist de scope die deze route vraagt. Maak een key met de juiste scopes aan.
live_not_enabled	403	Live mode is not enabled for this organisation De organisatie mag nog niet live. Werk met een `sk_test_`-key in de sandbox.
test_mode_only	403	Only available in test mode Deze route bestaat alleen in de sandbox, bijvoorbeeld de simulatie-endpoints.
turnstile_failed	403	Turnstile verification failed De Turnstile-controle van de publieke validator is niet gelukt: het token ontbreekt, is verlopen of is al gebruikt. Haal een nieuw token op en probeer het opnieuw.
two_factor_required	403	Two-factor authentication is required De consolesessie heeft nog geen tweede factor getoond, of het account heeft er geen terwijl de organisatie hem verplicht stelt. Alleen de console krijgt deze code; een API-key kent geen tweede factor.
invoice_not_available	404	The invoice is not available yet De zending is nog niet afgeleverd, dus er is nog geen factuur: een factuur volgt het afleverbewijs.
not_found	404	Not found De resource bestaat niet, of niet binnen deze organisatie en deze modus.
pod_not_available	404	The proof of delivery is not available yet De zending is nog niet afgeleverd, dus er is nog geen ePOD om op te halen.
already_signed	409	Already signed Voor deze rol is al een handtekening vastgelegd.
conflict	409	Conflict Het verzoek botst met de huidige staat van de resource.
field_frozen	409	Field is frozen in the current status Het veld ligt vast in de huidige status; na uitgifte zijn de vrachtbriefvelden bevroren.
idempotency_in_progress	409	A request with this idempotency key is still running Een eerder verzoek met deze `Idempotency-Key` loopt nog. Wacht en probeer opnieuw.
idempotency_key_reused	409	Idempotency key reused with a different request Dezelfde `Idempotency-Key` is gebruikt voor een andere body. Gebruik per verzoek een nieuwe sleutel.
invalid_state	409	The shipment is in the wrong state for this operation De zending staat in een status waarin deze operatie geen betekenis heeft.
invalid_transition	409	Invalid state transition De statusovergang is niet toegestaan door de state machine, bijvoorbeeld `delivered` na `cancelled`.
shipment_immutable	409	The shipment can no longer be changed De zending is afgerond of geannuleerd en verandert niet meer.
link_expired	410	Signed link expired De ondertekende link is verlopen. Vraag een nieuwe aan.
token_expired	410	The link has expired De inspectie- of tekenlink is verlopen.
token_revoked	410	The link was withdrawn De tekenlink is ingetrokken door de afzender. Vraag om een nieuwe link.
token_rotated	410	The link was replaced by a newer one De link is vervangen door een nieuwere; de oude werkt niet meer.
payload_too_large	413	Payload too large De body of het bestand is groter dan de limiet van de route.
unsupported_media_type	415	Unsupported media type Het `Content-Type` wordt niet ondersteund voor deze route.
identification_invalid	422	The identification is unknown, already used or expired Het `identification_token` is onbekend, al gebruikt, ouder dan vijftien minuten of hoort bij een andere ondertekenlink. Een identificatie geldt voor één handtekening. Vraag een nieuwe aan.
identification_required	422	This signature needs an identification at the trust service provider Deze ondertekenlink vraagt om `ades` of `qes`. Laat de ondertekenaar zich eerst identificeren met `POST /v1/sign/:token/identification` en stuur het `identification_token` mee. Geen fout maar een stap: de Sign-PWA toont hem als scherm, niet als foutmelding.
invoice_incomplete	422	The invoice misses something EN 16931 requires De zending of de query mist een gegeven dat EN 16931 verplicht stelt — bijvoorbeeld `charges.carriage`, het btw-tarief van een binnenlandse rit of het rekeningnummer van een Nederlandse verkoper. `detail` noemt welk.
otp_invalid	422	The one-time password is wrong or expired De eenmalige code klopt niet, is verlopen of is al gebruikt. Vraag een nieuwe aan met `POST /v1/sign/:token/otp`. Hetzelfde antwoord komt terug voor een `otp_verified_token` dat al verbruikt is.
subset_unknown	422	Unknown eFTI subset De gevraagde `subset` is geen eFTI-subset die dit platform projecteert. `GET /v1/shipments/:id/efti` zonder `subset` geeft de common dataset.
two_factor_invalid	422	The two-factor code is wrong, expired or already used De zescijferige code of de herstelcode klopt niet, is verlopen of is al gebruikt. Hetzelfde antwoord voor alle drie: welke van de drie het was, is precies wat een aanvaller wil weten.
validation_failed	422	Validation failed De body is syntactisch goed maar inhoudelijk fout. De `errors`-array benoemt per veld wat er mis is.
otp_locked	429	Too many wrong one-time passwords Vijf foute codes op rij: deze ontvanger is geblokkeerd tot het venster van tien minuten voorbij is. `Retry-After` zegt hoe lang.
rate_limited	429	Too many requests Te veel verzoeken. Respecteer `Retry-After` en de `RateLimit-*`-headers.
internal_error	500	Internal error Een onverwachte fout aan onze kant. Meld het `request_id` bij support.
pdf_render_failed	500	The consignment note PDF could not be rendered De vrachtbrief-PDF kon niet worden opgebouwd. Probeer het opnieuw en meld het `request_id` als het blijft mislukken.
not_implemented	501	Not implemented De route is al gedeclareerd maar nog niet gevuld.
provider_unavailable	502	The eCMR provider is unavailable De eCMR-provider achter deze route antwoordt niet. Probeer het later opnieuw.
billing_not_configured	503	Billing is not configured for this organisation Deze omgeving heeft geen facturatieprovider, dus er is geen klantportaal en er wordt niets in rekening gebracht. Verbruik is wel gewoon zichtbaar via `GET /v1/usage`.
qtsp_unavailable	503	The trust service provider is unavailable De vertrouwensdienst die `ades` en `qes` ondertekent is er niet, of weigerde. Zonder de binding `QTSP_PROVIDER` heeft deze omgeving er geen — in productie is dat de standaard, omdat een testcertificaat geen gekwalificeerde handtekening is. Ondertekenen op `platform_auth` blijft gewoon werken.
service_unavailable	503	Service unavailable De API is tijdelijk niet beschikbaar. Probeer het later opnieuw.