> For the complete documentation index, see [llms.txt](https://integration-guide.redeem.gov.sg/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://integration-guide.redeem.gov.sg/phase2-integration/api-documentation/errors/overview.md).

# Overview

### 6.1 Overview

RedeemSG uses conventional HTTP response codes to indicate the success or failure of an API request.

Codes in the <mark style="color:red;">`2xx`</mark> range indicate success. Codes in the <mark style="color:red;">`4xx`</mark> range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a redemption cannot be made, etc.). Codes in the <mark style="color:red;">`5xx`</mark> range indicate an error with RedeemSG’s servers.

The response body can include a <mark style="color:red;">`code`</mark>, with a short string indicating the error encountered

**Sample response in redeeming a used voucher:**

```json
// HTTP 402
{
  "error": {
    "code": "redemption_vouchers_used",
    "message": "voucher/s selected for redemption has already been used",
    "type": "invalid_request_error"
  },
}
```

**HTTP Status Code Summary**

| Status Code             | Description                                                                                                                                                                                                                        |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200 - OK                | Everything worked as expected.                                                                                                                                                                                                     |
| 400 - Bad Request       | The request was unacceptable, often due to a missing required parameter or an unexpected format.                                                                                                                                   |
| 401 - Unauthorized      | No valid credentials provided.                                                                                                                                                                                                     |
| 402 - Request Failed    | The parameters were valid but the request failed. 402 is not a clearly defined HTTP code, but in certain APIs is used when a resource’s state is concerned. (eg. voucher already redeemed, voucher voided, admin already removed). |
| 403 - Forbidden         | Your credentials doesn’t have permissions to perform the request.                                                                                                                                                                  |
| 404 - Not Found         | The requested resource doesn’t exist.                                                                                                                                                                                              |
| 409 - Conflict          | The request conflicts with another request (eg. same idempotent key).                                                                                                                                                              |
| 429 - Too Many Requests | Too many requests. We recommend an exponential backoff.                                                                                                                                                                            |
| 500 - Server Error      | Something went wrong on RedeemSG’s end                                                                                                                                                                                             |
| 503 - Server Error      | Something went wrong on RedeemSG’s end, caused by an external service                                                                                                                                                              |

**Error Types**

| Error Type              | Description                                                                                                                                                                                                                   |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| api\_error              | API errors indicate a issue with RedeemSG’s servers,                                                                                                                                                                          |
| external\_error         | External errors indicate an issue due to an external service utilized by RedeemSG, which prevented RedeemSG from completing the request (Eg. Singpass, Twilio, etc.).                                                         |
| idempotency\_error      | Idempotency errors occur when an <mark style="color:red;">`Idempotency-Key`</mark> is re-used on a request that does not match the first request's API endpoint and parameters or when the first request is still processing. |
| invalid\_request\_error | Invalid request errors arise when your request has invalid parameters.                                                                                                                                                        |