Errors

There are two kinds:

• DAWA's errors — a malformed parameter or path, or a record that does not exist. Same status, same body as DAWA, so DAWA error handling keeps working.
• Our refusals — the key, the plan's limits, the service. These are problem details (application/problem+json, RFC 9457). Where a body has a code, branch on it, never on the wording.

DAWA's errors

A body of type, title and details. The examples are DAWA's own answers.

QueryParameterFormatError — 400

A query parameter is malformed. details holds one [parameter, message] pair for each one that is wrong.

Request

GET https://api.getaddress.dk/adresser?per_side=abc&api-key={your-api-key} 

Response (400)

{
  "type": "QueryParameterFormatError",
  "title": "One or more query parameters was ill-formed.",
  "details": [
    [
      "per_side",
      "notInteger"
    ]
  ]
}

Request

GET https://api.getaddress.dk/adgangsadresser/reverse?api-key={your-api-key} 

Response (400)

{
  "type": "QueryParameterFormatError",
  "title": "One or more query parameters was ill-formed.",
  "details": [
    [
      "x",
      "Parameteren x skal angives"
    ],
    [
      "y",
      "Parameteren y skal angives"
    ]
  ]
}

ResourcePathFormatError — 404

The path is malformed: an id that is not a UUID, a postcode that is not a number.

Request

GET https://api.getaddress.dk/adresser/not-a-uuid?api-key={your-api-key} 

Response (404)

{
  "type": "ResourcePathFormatError",
  "title": "The URI path was ill-formed.",
  "details": [
    [
      "id",
      "String does not match pattern ^([0-9a-fA-F]{8}\\-[0-9a-fA-F]{4}\\-[0-9a-fA-F]{4}\\-[0-9a-fA-F]{4}\\-[0-9a-fA-F]{12})$: not-a-uuid"
    ]
  ]
}

ResourceNotFoundError — 404

No record with that id, postcode or street name. It costs nothing.

Request

GET https://api.getaddress.dk/adresser/00000000-0000-0000-0000-000000000000?api-key={your-api-key} 

Response (404)

{
  "type": "ResourceNotFoundError",
  "title": "The resource was not found",
  "details": {
    "id": "00000000-0000-0000-0000-000000000000"
  }
}

Our refusals

unauthorized — 401

No api-key, a key or domain token we don't know, or an API key sent from a web page (see Authentication).

{
    "type": "https://getaddress.dk/docs/errors#unauthorized",
    "title": "Unauthorized",
    "status": 401,
    "detail": "The api-key query string parameter is missing or invalid.",
    "code": "unauthorized"
}

forbidden — 403

The key is genuine but may not do this: the admin key used for an address request, or an API key used for /usage. An address request on a subscription that has ended is refused with 403 too.

domain-token-scope — 403

A domain token was used for something other than an address request, such as /usage. Call it from your server with the right key.

domain-token-rate-limit — 429

The domain token's per-visitor or token-wide limit was reached. Wait the number of seconds in Retry-After.

Rate limit — 429

Your plan's requests per 5 minutes are used up. Retry-After says when the next span starts.

Daily limit, monthly buffer — 429

Your plan's look-ups for today are used up, and any monthly buffer with them. Metered endpoints refuse until midnight UTC (Retry-After says how long); free endpoints keep answering. See Usage.

Service unavailable — 503

The address data or the key store was briefly out of reach. Retry shortly.