> ## Documentation Index
> Fetch the complete documentation index at: https://giftbit.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP success and error codes

> Your API integration should always check the HTTP response code to ensure correct handling of success and error conditions.

Only an HTTP status of **200** means the request was successful.

For non-200 responses, the predictable response body (described below) will give you details on why the request failed.

We suggest logging any failure response body as best practice; the Giftbit support team will need the full response body to assist with troubleshooting. This section gives details on the response codes and recommended actions.

## Success responses

> [!TIP]
>
> **200**: Success. See the [API reference](https://giftbit.mintlify.site/api-reference) for the response format of each endpoint.

## Error responses

All non-200 responses should be treated as an error and either retried, or the request fixed and then retried. This section details the different potential non-200 responses.

To assist with your programmatic error handling and troubleshooting, all error response bodies are returned in the following JSON format:

```json theme={null}
{
  "error": {
    "code": "<value>",
    "name": "<value>",
    "message": "<value>"
  },
  "status": <value>
}
```

* **`code`** — an enum-style error code that represents the problem and will not change.
* **`name`** — a human-readable error name.
* **`message`** — request-specific information about the error.
* **`status`** — an integer that matches the HTTP status code returned.

### Example

```json theme={null}
{
  "error": {
    "code": "ERROR_CAMPAIGN_INVALID_BRAND",
    "name": "Invalid Brand or Brand/Price combination",
    "message": "brand_code: itunesus - price_in_cents: 50000 - The brand_code provided is not valid or not available for the given price"
  },
  "status": 422
}
```

## Error response codes

> **400 — Malformed request**
>
> Error due to a malformed request body such as broken JSON or missing required element. Requires fixing up the request body.

> **401 / 403 — Authentication or authorization failure**
>
> Generally related to a missing or invalid API key. Ensure you are [authenticating](https://giftbit.mintlify.site/guides/authentication.md) correctly.

> **402 — Credit card charge failure**
>
> The request was correct, but the card was not charged.

> **422 — Invalid parameters**
>
> The request is formatted correctly, but one or more parameters in the body or URL are not valid. An example would be trying to create an order with a reward value outside of the allowed range for that brand. Ensure the request parameters are valid.

> **429 — Too many requests**
>
> The Giftbit API uses adaptive rate limiting that allows burstiness and should generally not interfere with valid usage patterns. If you receive a `429` response, your code should automatically retry the request with a backoff delay.
>
> You can simulate rate limiting in the Testbed environment — without actually producing a high request rate — by passing a `SIMULATE-RATELIMIT` header with a value of `true` on any request. If you feel you are being frequently rate limited during valid usage, please contact support.

> **5xx — Unexpected error**
>
> An unexpected error on the Giftbit side. Retry the request, and if failures persist, contact support. Note that the response body format in the `5xx` case may not match the common error response format described above.

## Handling timeouts

If you receive a network timeout or other unexpected response (such as a `5xx`) when creating an order or an embedded reward, resend the `POST` request to `/campaign`, `/direct_links`, or `/embedded` using the same supplied `id`.

> [!NOTE]
>
> The supplied `id` is idempotent — Giftbit will only ever create one order with a given supplied `id`. The supplied `id` must always be unique across different requests.

We ask for, and recommend using exponential backoff with a limited number of tries for timeouts and unexpected responses (such as a `5xx`), with clear logging or alerts to allow for investigation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.