Errors and status codes

The API uses standard HTTP status codes and returns errors as JSON. Applications should check the HTTP status before processing the response body.

Error response

An error response can contain a status code, machine-readable error identifier and human-readable message:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "radius_km requires near or both lat and lon"
}

Do not build application logic around the human-readable message. Messages may become clearer over time without constituting an API contract change. Use the HTTP status and a machine-readable error code when one is provided.

Common status codes

Status	Meaning	Recommended action
200 OK	The request succeeded	Process the response
400 Bad Request	A parameter or request value is invalid	Correct the request before retrying
401 Unauthorized	The API key is missing, invalid or revoked	Check the Bearer token
403 Forbidden	The key is valid but lacks permission	Request the required scope or use another key
404 Not Found	The requested resource does not exist	Verify the endpoint and club slug
429 Too Many Requests	The applicable rate limit was exceeded	Wait before retrying
500 Internal Server Error	The API could not complete the request	Retry later with backoff
502 Bad Gateway	A required upstream service failed	Retry later with backoff
503 Service Unavailable	The service is temporarily unavailable	Retry later with backoff

Place search may return location_not_found, geocoding_api_key_invalid, geocoding_configuration_error, geocoding_quota_exceeded, geocoding_failed or geocoding_unavailable. See place and radius search.

Handle errors in JavaScript

const response = await fetch(
  'https://api.eae.golf/v1/clubs?limit=20',
  {
    headers: {
      Authorization: `Bearer ${apiKey}`,
      Accept: 'application/json'
    }
  }
);

const body = await response.json().catch(() => null);

if (!response.ok) {
  throw new Error(
    body?.message ?? `API request failed with status ${response.status}`
  );
}

Retrying requests

Do not automatically retry validation, authentication or permission errors. The request must be corrected first.

Temporary server errors and rate-limit responses may be retried. Use exponential backoff with a small random delay and respect Retry-After whenever the header is present.

Avoid unlimited retries. Set a maximum number of attempts and report a useful error when the API remains unavailable.

Request identifiers

When a response contains a request identifier, record it in application logs. Include that identifier when reporting an API problem, but never include the API key itself.