API Responses

Response Format

All API responses follow a consistent JSON structure, making it easy to parse and handle responses in your application.

Success Responses

Successful requests return a 200 status code with the requested data:

{
  "data": {
    "id": "order_abc123",
    "status": "completed",
    "created_at": "2025-10-11T10:30:00Z"
  },
  "request_id": "0e8400-e29b..."
}

Error Responses

Failed requests return an appropriate error status code with detailed error information:

{
    "message": "Invalid request parameters",
    "errors": {
        "login": "The 'login' field is required"
    },
    "request_id": "0e8400-e29b..."
}

Always include the request_id when contacting support. This helps us quickly locate and troubleshoot your specific request.

HTTP Status Codes

The GameBoost API uses standard HTTP status codes to indicate the success or failure of requests.

Success Codes

Status Code	Meaning	Description
`200`	Success	Request completed successfully
`204`	Success (No Content)	Request successful but no data to return

Client Error Codes

These errors indicate issues with your request or authentication

Status Code	Meaning	Likely Reason
`400 Bad Request`	Invalid Request	The request syntax is malformed or contains invalid parameters
`401 Unauthorized`	Authentication Failed	Missing, invalid, or expired API key
`403 Forbidden`	Access Denied	Valid authentication but insufficient permissions for this resource
`404 Not Found`	Resource Not Found	The requested resource doesn’t exist or you don’t have access to it
`422 Unprocessable Entity`	Validation Failed	Request syntax is correct but data validation failed
`429 Too Many Requests`	Rate Limited	You’ve exceeded the rate limit. Slow down your requests

Server Error Codes

These errors indicate issues on our servers or infrastructure

Status Code	Meaning	Likely Reason
`500 Internal Server Error`	Server Error	An unexpected error occurred on our servers. Try again later
`502 Bad Gateway`	Gateway Error	Temporary issue with our infrastructure. Retry with exponential backoff
`503 Service Unavailable`	Service Down	The service is temporarily unavailable. Check our status page
`504 Gateway Timeout`	Request Timeout	The request took too long to process. Try again or simplify your request

Error Response Examples

401 Unauthorized

Cause: Missing or invalid authentication credentials.

{
  "message": "Unauthorized access",
  "request_id": "0e8400-e29b..."
}

How to fix: Ensure you’re including a valid API key in the Authorization header. See our Authentication Guide.

403 Forbidden

Cause: You don’t have permission to access this resource.

{
    "message": "Unauthorized access",
    "request_id": "0e8400-e29b..."
}

How to fix: Verify the resource you’re trying to access belongs to you.

404 Not Found

Cause: The requested resource doesn’t exist or you don’t have access to it.

{
    "message": "Resource not found",
    "request_id": "0e8400-e29b..."
}

How to fix: Double-check the resource ID in your request. Ensure the resource exists and you have access to it.

422 Unprocessable Entity

Cause: Request validation failed due to invalid data.

{
    "message": "The account data is invalid",
    "errors": {
        "credentials.email_login": "The credentials.email_login field must be a valid email address",
        "account_data.server": "The account_data.server field must be one of: EU, US, etc."
    },
    "request_id": "0e8400-e29b...",
}

How to fix: Review the errors object and correct the specified fields.

429 Too Many Requests

Cause: You’ve exceeded the API rate limit.

{
    "message": "Too many requests",
    "request_id": "0e8400-e29b..."
}

How to fix: Implement exponential backoff and respect the Retry-After header. See our Rate Limiting Guide.

500 Internal Server Error

Cause: An unexpected error occurred on GameBoost’s servers.

{
    "message": "An internal server error occurred",
    "request_id": "0e8400-e29b..."
}

How to fix: This is an issue on our end. Try again in a few moments. If the problem persists, contact us with the request_id.

503 Service Unavailable

Cause: The API is temporarily unavailable, usually due to maintenance.

{
    "message": "Service temporarily unavailable",
    "request_id": "0e8400-e29b...",
}

How to fix: Wait for the specified Retry-After seconds and try again. Check our status page for updates.

Handling Errors

Best Practices

Always check status codes

Don’t rely solely on the presence of data in the response. Always check the HTTP status code to determine if the request was successful.

const response = await fetch('https://api.gameboost.com/v2/orders', {
  headers: { 'Authorization': `Bearer ${apiKey}` }
});

if (!response.ok) {
  const errorData = await response.json();
  console.error(`Error ${response.status}:`, errorData.message);
  console.error(`Request ID:`, errorData.request_id);
  throw new Error(errorData.message);
}

const data = await response.json();

Parse error details

Extract useful information from error responses to provide better feedback to users or for debugging.

try {
  const response = await fetch(url, options);
  if (!response.ok) {
    const errorData = await response.json();

    // Log the request_id for support
    console.error('Request ID:', errorData.request_id);

    // Handle specific error types
    if (response.status === 429) {
      // Rate limited - check headers for retry timing
      const retryAfter = response.headers.get('Retry-After');
      await sleep(parseInt(retryAfter) * 1000);
      return retry();
    }

    if (response.status === 422 && errorData.errors) {
      // Validation errors
      return handleValidationErrors(errorData.errors);
    }

    // Generic error
    throw new Error(errorData.message);
  }
} catch (error) {
  console.error('API request failed:', error);
}

Implement retry logic

For transient errors (5xx status codes), implement retry logic with exponential backoff.

async function apiRequestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);

      if (response.ok) {
        return await response.json();
      }

      // Retry on server errors
      if (response.status >= 500) {
        const backoff = Math.pow(2, attempt) * 1000;
        console.log(`Server error, retrying in ${backoff}ms...`);
        await sleep(backoff);
        continue;
      }

      // Don't retry client errors
      const error = await response.json();
      throw new Error(error.message);

    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
    }
  }
}

Log request IDs

Always log the request_id from error responses. This is invaluable when contacting support.

function logError(errorData, response, context) {
  console.error({
    timestamp: new Date().toISOString(),
    request_id: errorData.request_id,
    status_code: response.status,
    message: errorData.message,
    errors: errorData.errors,
    context: context
  });
}

Error Handling Example

Here’s a complete example of robust error handling:

class GameBoostAPI {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.gameboost.com/v2';
  }

  async request(endpoint, options = {}) {
    const url = `${this.baseUrl}${endpoint}`;
    const headers = {
      'Authorization': `Bearer ${this.apiKey}`,
      'Content-Type': 'application/json',
      ...options.headers
    };

    try {
      const response = await fetch(url, { ...options, headers });

      // Success
      if (response.ok) {
        return await response.json();
      }

      // Parse error response
      const errorData = await response.json();

      // Handle specific error types
      switch (response.status) {
        case 401:
          throw new AuthenticationError(errorData, response);
        case 403:
          throw new PermissionError(errorData, response);
        case 404:
          throw new NotFoundError(errorData, response);
        case 422:
          throw new ValidationError(errorData, response);
        case 429:
          throw new RateLimitError(errorData, response);
        case 500:
        case 502:
        case 503:
        case 504:
          throw new ServerError(errorData, response);
        default:
          throw new APIError(errorData, response);
      }

    } catch (error) {
      console.error('API Request Failed:', {
        endpoint,
        status: error.status,
        message: error.message,
        request_id: error.request_id
      });
      throw error;
    }
  }
}

// Custom error classes
class APIError extends Error {
  constructor(errorData, response) {
    super(errorData.message);
    this.message = errorData.message;
    this.request_id = errorData.request_id;
    this.status = response.status;
    this.response = response;
  }
}

class ValidationError extends APIError {
  constructor(errorData, response) {
    super(errorData, response);
    this.errors = errorData.errors; // Object with field: error message pairs
  }
}

class RateLimitError extends APIError {
  constructor(errorData, response) {
    super(errorData, response);
    // Get retry timing from headers
    this.retry_after = parseInt(response.headers.get('Retry-After')) || 60;
    this.limit = parseInt(response.headers.get('X-RateLimit-Limit'));
    this.reset = parseInt(response.headers.get('X-Ratelimit-Reset'));
  }
}

Response Headers

All API responses include helpful headers for debugging and rate limiting:

Header	Description
`X-Gameboost-Request-Id`	Unique identifier for this request (same as in response body)
`X-RateLimit-Limit`	Your rate limit cap for this endpoint type
`X-RateLimit-Remaining`	Number of requests remaining in the current window
`X-Ratelimit-Reset`	Unix timestamp when the rate limit resets
`Retry-After`	Seconds to wait before retrying (only when rate limited)

Monitor the X-RateLimit-Remaining header to implement proactive rate limiting in your application.

Next Steps

Rate Limiting

Learn how to handle rate limits effectively

Webhooks

Set up real-time event notifications

API Reference

Explore all available endpoints

Authentication

Review authentication setup

Getting Started

REST API

Webhooks

Response Format

Success Responses

Error Responses

HTTP Status Codes

Success Codes

Client Error Codes

Server Error Codes

Error Response Examples

401 Unauthorized

403 Forbidden

404 Not Found

422 Unprocessable Entity

429 Too Many Requests

500 Internal Server Error

503 Service Unavailable

Handling Errors

Best Practices

Error Handling Example

Response Headers

Next Steps

Rate Limiting

Webhooks

API Reference

Authentication

Getting Started

REST API

Webhooks

​Response Format

​Success Responses

​Error Responses

​HTTP Status Codes

​Success Codes

​Client Error Codes

​Server Error Codes

​Error Response Examples

​401 Unauthorized

​403 Forbidden

​404 Not Found

​422 Unprocessable Entity

​429 Too Many Requests

​500 Internal Server Error

​503 Service Unavailable

​Handling Errors

​Best Practices

​Error Handling Example

​Response Headers

​Next Steps

Rate Limiting

Webhooks

API Reference

Authentication

Response Format

Success Responses

Error Responses

HTTP Status Codes

Success Codes

Client Error Codes

Server Error Codes

Error Response Examples

401 Unauthorized

403 Forbidden

404 Not Found

422 Unprocessable Entity

429 Too Many Requests

500 Internal Server Error

503 Service Unavailable

Handling Errors

Best Practices

Error Handling Example

Response Headers

Next Steps