Feilsvar og grenser

Feilsvar

Alle feil har samme form, med requestId som du kan oppgi hvis du kontakter oss. Den står også i headeren X-Request-ID på alle svar.

{"error": {"status": 401, "message": "…", "requestId": "9c38fd23f4c14471b86c023902341627"}}

Status	Betyr	Gjør dette
400	Ugyldig forespørsel	Les message
401	Nøkkel mangler, er ugyldig, utløpt eller tilbakekalt	Send nøkkelen i X-API-Key. Svaret har registerUrl
403	Kallet krever et høyere nivå	Semantisk søk krever ext. Se Tilgangsnivåer
404	Verket finnes ikke, eller er ikke publisert	Sjekk nmId
422	Feil i parametre eller kropp	details sier hvilket felt
429	For mange kall	Vent så mange sekunder som Retry-After sier
5xx	Feil hos oss	Prøv igjen litt senere. Vedvarer det, kontakt oss med requestId

Ett unntak: når nøkkelen mangler, er message et objekt med lenker til vilkårene og registreringen (registerUrl, termsUrl). Programmer som viser message, må tåle begge formene.

Uten nøkkel:

Uten nøkkel: 401 med lenke til registreringen

curl -s -w "\nHTTP %{http_code}\n" "https://api.nasjonalmuseet.no/api/v1/objects/NG.M.00939"

Ratebudsjett

Kall	Grense per nøkkel
Verk, bla, tekstsøk, IIIF	120 per minutt
Bilder (/multimedia)	60 per minutt
Søk (/search/*)	30 per minutt
Linked Art (/api/linkedart/*)	120 per minutt per IP-adresse

Ved overskridelse svarer API-et 429 med Retry-After (sekunder), X-RateLimit-Remaining og X-RateLimit-Reset. Vent og prøv igjen:

import os import time import requests

API = "https://api.nasjonalmuseet.no/api/v1" headers = {"X-API-Key": os.environ["NM_API_KEY"]}

def hent(url, **kw): """GET med respekt for ratebegrensningen: ved 429 venter vi Retry-After sekunder.""" for _ in range(5): r = requests.get(url, headers=headers, timeout=30, **kw) if r.status_code != 429: r.raise_for_status() return r.json() time.sleep(int(r.headers.get("Retry-After", "5"))) raise RuntimeError("Ga opp etter fem forsøk")

print(hent(f"{API}/objects/NG.M.00939")["mainTitle"])

Trenger en offentlig tjeneste mer, kan nøkkelen få egen grense. Kontakt oss.

Nøkkelen

• Varer i 180 dager. Forny den på registreringssiden før den går ut.
• Del den ikke. Hver person eller tjeneste lager sin egen.
• Legg den ikke i adressen (?api_key=). Den virker ikke der, og havner i logger.