Guides

Error Handling

Error Handling

The GG365 Golf API uses standard HTTP status codes and returns error details in a consistent format.

Error Response Format

Code
 
{
  "error": {
    "code": "invalid_tee_time",
    "message": "The requested tee time is no longer available.",
    "details": {
      "courseId": "course_123",
      "date": "2023-07-15",
      "time": "08:30"
    },
    "requestId": "req_abcdef123456"
  }
}

All error responses include:

Field	Description
code	Machine-readable error code
message	Human-readable error description
details	Additional context about the error (varies by error type)
requestId	Unique identifier for the request (useful for support)

HTTP Status Codes

Status Code	Description
400	Bad Request - Invalid input parameters or request body
401	Unauthorized - Missing or invalid API key
403	Forbidden - Valid API key, but insufficient permissions
404	Not Found - Resource does not exist
409	Conflict - Resource state conflicts with request (e.g., already booked)
422	Unprocessable Entity - Request validation failed
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Something went wrong on our end
503	Service Unavailable - API is temporarily unavailable

Common Error Codes

Authentication Errors

Error Code	Description
missing_api_key	No API key was provided in the request
invalid_api_key	The provided API key is invalid or revoked
expired_api_key	The API key has expired
insufficient_permissions	The API key doesn't have permission for this action

Validation Errors

Error Code	Description
invalid_request	General validation error for request body
missing_required_field	A required field is missing
invalid_field_format	A field has an invalid format
invalid_date	Date format is incorrect or date is invalid
invalid_player_count	Number of players is invalid for this course
invalid_handicap	Handicap value is outside the allowed range

Booking Errors

Error Code	Description
course_not_found	The requested course does not exist
booking_not_found	The requested booking does not exist
invalid_tee_time	The requested tee time is unavailable
tee_time_expired	The hold on the tee time has expired
course_fully_booked	No tee times available on the requested date
booking_already_cancelled	The booking is already in cancelled state
booking_modification_not_allowed	The booking can no longer be modified
offline_booking_required	This course requires offline booking

System Errors

Error Code	Description
internal_error	Internal server error
service_unavailable	Service is temporarily unavailable
provider_error	Error from third-party provider
database_error	Database operation failed

Handling Rate Limit Errors

When you exceed your rate limit, you'll receive a 429 Too Many Requests response:

Code
 
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 45 seconds.",
    "details": {
      "retryAfter": 45,
      "limit": 60,
      "remaining": 0,
      "resetAt": 1620000000
    },
    "requestId": "req_ratelimit123"
  }
}

Best Practices for Rate Limits

1. Check the X-RateLimit-Remaining header to monitor your usage
2. When you receive a 429 error, use the retryAfter value to wait before retrying
3. Implement exponential backoff for repeated rate limit errors
4. Consider caching frequently accessed data to reduce API calls

Error Handling Best Practices

1. Always check the status code first to determine the type of error
2. Parse the error code for programmatic handling of specific errors
3. Display the error message to users when appropriate
4. Log the requestId for troubleshooting with support
5. Implement retry logic for 429 and 5xx errors
6. Validate inputs before sending requests to avoid validation errors

Example: Handling Unavailable Tee Times

When a tee time becomes unavailable during the booking process:

Code
 
try {
  const response = await api.createBooking(bookingData);
  // Handle successful booking
} catch (error) {
  if (error.status === 409 && error.data.error.code === 'invalid_tee_time') {
    // The tee time is no longer available
    // Suggest alternative tee times to the user
    const alternatives = await api.getTeeTimeAlternatives({
      courseId: error.data.error.details.courseId,
      date: error.data.error.details.date,
      time: error.data.error.details.time
    });
    
    // Display alternatives to user
  } else {
    // Handle other errors
    console.error(`Error ${error.status}: ${error.data.error.message}`);
    // Log for support
    console.log(`Request ID: ${error.data.error.requestId}`);
  }
}

Getting Help with Errors

If you encounter persistent errors or need help debugging an issue:

1. Note the requestId from the error response
2. Check if the error is documented in this guide
3. Contact API support at [email protected] with the requestId and details