Error Handling

The API uses standard HTTP status The Giftoin API uses standard HTTP status codes to indicate the success or failure of an API call. Understanding these error codes will help you troubleshoot issues and handle errors gracefully in your application.

• 200 (OK) - The request was successful

• 400 (Bad Request) - The server could not process the request, most likely because of an invalid argument

• 401 (Unauthorized) - Your request lacks valid authentication credentials, your API key is missing in the request headers

• 402 (Payment Required) - Your API request was rejected due to it being a paid subscription plan with an overdue balance

• 403 (Forbidden) - Your request was rejected due to a permission issue, likely a restriction on the API Key's associated service plan

• 404 (Not Found) - The requested resource was not found

• 429 (Too Many Requests) - The API Key's rate limit was exceeded

• 500 (Internal Server Error) - An unexpected server issue was encountered

Error Response Codes

When an error occurs, the API returns a JSON response with a status object containing:

• timestamp - The time when the error occurred

• errorCode - A numeric code specific to the error

• errorMessage - A human-readable description of the error

{
    "status": {
        "timestamp": "1708777200000",
        "errorCode": 5250,
        "errorMessage": "Campaign not found"
    }
}

Error Code Reference

Here's a reference of specific error codes you might encounter:

HTTP Status	Error Code	Error Message
400	1001 [API_KEY_INVALID]	This API Key is invalid.
401	1002 [API_KEY_MISSING]	API key missing.
404	5250[CAMPAIGN_NOT_FOUND]	Campaign not found
404	5252[CAMPAIGN_ORDER_NOT_FOUND]	Order not found

Handling Errors in Your Code

Here are some best practices for handling API errors:

1. Check for HTTP status codes first - Handle different categories of errors differently (e.g., client errors vs. server errors)

2. Parse the error message and code - Extract specific information about what went wrong

3. Implement retry logic for certain errors - For example, retrying after a brief delay for rate limit errors (429)

4. Log detailed error information - Store the complete error response for debugging

5. Provide user-friendly error messages - Translate API errors into helpful information for your users

Example error handling in JavaScript:

fetch('https://api.giftoin.org/api/v1/gcm/reseller/campaign/invalid_id')
  .then(response => {
    if (!response.ok) {
      return response.json().then(errorData => {
        throw {
          status: response.status,
          errorCode: errorData.status.errorCode,
          message: errorData.status.errorMessage
        };
      });
    }
    return response.json();
  })
  .then(data => {
    // Handle successful response
    console.log('Success:', data);
  })
  .catch(error => {
    // Handle error
    console.error('Error:', error);
    
    // User-friendly error messages
    if (error.errorCode === 5250) {
      displayUserMessage("We couldn't find that campaign. Please check the ID and try again.");
    } else if (error.errorCode === 5255) {
      displayUserMessage("This campaign is out of stock. Please contact support to increase the limit.");
    } else if (error.status === 429) {
      displayUserMessage("You've made too many requests. Please wait a moment and try again.");
    } else {
      displayUserMessage("Something went wrong. Please try again later or contact support.");
    }
  });