Errors

Every non-2xx response uses the same envelope:

{
  "error": {
    "code": "invalid_request",
    "message": "Unknown field: foo"
  }
}

Field	Type	Description
code	string	Stable, machine-readable error code.
message	string	Human-readable description.
details	object	Optional extra context. Present only for some errors.

Codes

Status	Code	When
400	invalid_request	Unknown field, missing/empty required field, malformed JSON body, invalid date, or checkoutDate before checkinDate.
401	unauthorized	Missing or incorrect bearer token.
404	not_found	No route matches the method and path.
404	place_not_found	/v1/places/:placeId — no such place.
404	event_not_found	/v1/events/:eventId — no such event.
422	hotel_not_resolved	The hotel could not be confidently resolved to a place with coordinates.
429	rate_limited	The sandbox key exceeded its request quota (10,000/day or 100/min). Production limits are negotiated per key.
502	upstream_unavailable	An upstream dependency failed.
504	upstream_timeout / request_timeout	A dependency timed out, or the request exceeded its budget.
500	internal_error	Unexpected server failure.

invalid_request

The message names the offending field:

{
  "error": {
    "code": "invalid_request",
    "message": "Unknown field: hotelId"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: checkinDate"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "checkoutDate must be on or after checkinDate"
  }
}

A body that is not valid JSON:

{
  "error": {
    "code": "invalid_request",
    "message": "Malformed JSON body"
  }
}

unauthorized

Returned when the Authorization header is missing, is not a Bearer token, or carries the wrong token:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid bearer token"
  }
}

not_found

Returned for any request that does not match a known route:

{
  "error": {
    "code": "not_found",
    "message": "No route for GET /v1/unknown"
  }
}

place_not_found / event_not_found

Returned with 404 by a detail route when the id is valid but unknown. A dependency outage is never reported as a 404 — that is a 502/504 — so a caller can tell "no such place" apart from "we're down".

{
  "error": {
    "code": "place_not_found",
    "message": "Place not found"
  }
}

hotel_not_resolved

Returned with 422 when no confident hotel match is found. The details object carries the candidates that were considered, so the caller can see what the resolver saw:

{
  "error": {
    "code": "hotel_not_resolved",
    "message": "Could not resolve the hotel for this request",
    "details": {
      "candidates": [
        {
          "placeId": "…",
          "name": "Some Other Hotel",
          "label": "Some Other Hotel, Portland, ME, USA",
          "address": "123 Main St",
          "locality": "Portland",
          "region": "ME",
          "lat": 43.65,
          "lng": -70.25
        }
      ]
    }
  }
}

To improve the chance of resolution, send the most complete hotelName, hotelAddress, hotelCity, and hotelState you have.

rate_limited

Returned when a sandbox key exceeds its request quota: 10,000 requests per day or 100 requests per minute, counted per key. Requests are rejected until the window clears. Production limits are negotiated per key.

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded for this API consumer"
  }
}

internal_error

Returned for unexpected failures. The message is deliberately generic; the server log carries the underlying error.

{
  "error": {
    "code": "internal_error",
    "message": "Failed to process request"
  }
}