Errors and quotas

Errors use Problem Details. Keep X-Request-ID for support requests.

HTTP statuses

Status	Code	Meaning	Current V1
`400`	`INVALID_REQUEST`	Invalid parameter	Emitted
`401`	`MISSING_API_KEY / INVALID_API_KEY`	Missing, invalid or revoked key	Emitted
`403`	`FORBIDDEN`	Reserved for future authorization rules	Reserved
`404`	`RESOURCE_NOT_FOUND / ROUTE_NOT_FOUND`	Unknown resource or route	Emitted
`405`	`METHOD_NOT_ALLOWED`	Reserved for unsupported operations	Reserved
`409`	`CONFLICT`	Reserved for future write operations; never emitted by read-only V1	Reserved
`415`	`UNSUPPORTED_MEDIA_TYPE`	Reserved for future requests with a body	Reserved
`422`	`UNPROCESSABLE_CONTENT`	Reserved for future business validation	Reserved
`429`	`QUOTA_EXHAUSTED / TOO_MANY_REQUESTS`	Minute, monthly or global limit reached	Emitted
`500`	`INTERNAL_ERROR`	Internal error with request ID	Emitted
`502`	`UPSTREAM_ERROR`	Reserved for future upstream dependencies	Reserved
`503`	`SERVICE_UNAVAILABLE`	Reserved for temporary API unavailability	Reserved

Uniform format

Every emitted error uses application/problem+json. The code field is stable for automation; title and detail remain human-readable.

application/problem+json400

{
  "type": "https://fenua-api.pacificknowledge.dev/problems/invalid-request",
  "code": "INVALID_REQUEST",
  "title": "Invalid request",
  "status": 400,
  "detail": "One or more request parameters are invalid.",
  "instance": "/api/v1/places/search?q=",
  "requestId": "req_01HZZ2FENUA",
  "errors": [
    {
      "code": "INVALID_PARAMETER",
      "message": "must NOT have fewer than 1 characters",
      "path": "/q"
    }
  ]
}

Quota headers

RateLimit-Limit: 60
RateLimit-Remaining: 42
RateLimit-Reset: 1787900400
Retry-After: 18
X-Request-ID: req_01HZZ2FENUA
X-Data-Version: 2026.2

After a 429 response

Wait for the duration in Retry-After before retrying. 5xx errors are not counted against minute or monthly quotas.