# 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

<br>

### 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

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

### Error Code Reference

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

<table><thead><tr><th width="144.33333333333331">HTTP Status</th><th width="352">Error Code</th><th>Error Message</th></tr></thead><tbody><tr><td>400</td><td>1001 [API_KEY_INVALID]</td><td>This API Key is invalid.</td></tr><tr><td>401</td><td>1002 [API_KEY_MISSING]</td><td>API key missing.</td></tr><tr><td>404</td><td>5250[CAMPAIGN_NOT_FOUND]</td><td>Campaign not found</td></tr><tr><td>404</td><td>5252[CAMPAIGN_ORDER_NOT_FOUND]</td><td>Order not found</td></tr></tbody></table>

### 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:

```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.");
    }
  });
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.giftoin.org/api-reference/error-handling.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.