Error Handling

Understand API errors and how to handle them.

Error Response Format

All API errors return a consistent JSON structure:

json

{
  "error": "invalid_api_key",
  "message": "The API key provided is invalid or has been revoked.",
  "docs": "https://golfly.dev/docs/errors"
}

Status Codes

Status	Error Code	Description
200	—	Success
400	invalid_parameter	Invalid query parameter value
401	missing_api_key	No API key provided
401	invalid_api_key	API key is invalid or revoked
403	upgrade_required	Feature requires higher plan
404	course_not_found	Course ID doesn't exist
429	rate_limit_exceeded	Per-minute limit exceeded
429	daily_limit_exceeded	Daily quota reached (Free plan)
500	internal_error	Server error

Error Details

401Authentication Errors

missing_api_key

No API key was provided.

Fix: Add the x-api-key header to your request.

invalid_api_key

The API key doesn't exist or was revoked.

Fix: Check for typos, verify the key in your dashboard, or generate a new key.

403Permission Errors

upgrade_required

Your plan doesn't include this feature.

Affected endpoint:/courses/:id/holes requires Pro or Enterprise.

404Resource Errors

course_not_found

The requested course ID doesn't exist.

Fix: Verify the ID using GET /courses.

429Rate Limit Errors

rate_limit_exceeded

You've exceeded your per-minute rate limit.

daily_limit_exceeded

Free plan: 50 requests/day limit reached.

Tip: Check the X-RateLimit-Reset header to know when you can retry.

500Server Errors

internal_error

An unexpected error occurred on our servers.

Fix: Wait a few seconds and retry. If persistent, contact support.

Handling Errors in Code

javascript

async function fetchCourses(state) {
  const response = await fetch(
    `https://golfly.dev/api/v1/courses?state=${state}`,
    { headers: { 'x-api-key': API_KEY } }
  );

  if (!response.ok) {
    const error = await response.json();

    switch (response.status) {
      case 401:
        throw new Error(`Authentication failed: ${error.message}`);
      case 403:
        throw new Error('Upgrade required for this feature');
      case 429:
        const resetTime = response.headers.get('X-RateLimit-Reset');
        throw new Error(`Rate limited. Retry after ${resetTime}`);
      case 404:
        return []; // No courses found
      default:
        throw new Error(error.message || 'API request failed');
    }
  }

  return response.json();
}