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

# Errors

> HTTP status codes and error reference for the Rewards API.

All errors return JSON with an `error` field describing the problem.

```json theme={null}
{ "error": "Trigger not found" }
```

***

## HTTP status codes

| Status | Meaning                                       |
| ------ | --------------------------------------------- |
| `200`  | Success                                       |
| `400`  | Bad request — missing or invalid parameters   |
| `401`  | Unauthenticated — missing or invalid API key  |
| `403`  | Forbidden — valid key but insufficient access |
| `404`  | Not found — resource doesn't exist            |
| `429`  | Rate limited — slow down your requests        |
| `500`  | Internal server error — contact support       |

***

## Error reference

### Authentication

| Error                                                             | Status | Fix                                                                      |
| ----------------------------------------------------------------- | ------ | ------------------------------------------------------------------------ |
| `Missing API key`                                                 | 401    | Add `Authorization: Bearer rw_...` header                                |
| `Invalid API key format`                                          | 401    | Key must start with `rw_`                                                |
| `Invalid API key`                                                 | 401    | Key revoked or doesn't exist — generate a new one                        |
| `This API key does not have access to the specified point system` | 403    | Assign the point system to your key under Account → Integration → Access |

### Triggers

| Error                                                               | Status | Fix                                                             |
| ------------------------------------------------------------------- | ------ | --------------------------------------------------------------- |
| `Missing required fields: triggerKey, walletAddress, pointSystemId` | 400    | Include all three fields in the request body                    |
| `Invalid JSON body`                                                 | 400    | Ensure `Content-Type: application/json` and valid JSON          |
| `Trigger not found`                                                 | 404    | Check the `triggerKey` in your Triggers dashboard               |
| `Trigger is inactive`                                               | 403    | Enable the trigger toggle in the Triggers dashboard             |
| `Wallet is blacklisted`                                             | 403    | This wallet has been blacklisted in the point system            |
| `Rate limit exceeded`                                               | 429    | Max 10 calls/min per (key + wallet + trigger) — check for loops |

### Leaderboard / Activity

| Error                                       | Status | Fix                                     |
| ------------------------------------------- | ------ | --------------------------------------- |
| `Missing required parameter: pointSystemId` | 400    | Add `pointSystemId` to the query string |

### Wallet

| Error                                       | Status | Fix                                                 |
| ------------------------------------------- | ------ | --------------------------------------------------- |
| `Missing required parameter: pointSystemId` | 400    | Add `pointSystemId` to the query string             |
| `Missing required parameter: address`       | 400    | Add `address` to the query string                   |
| `Wallet not found in this point system`     | 404    | Wallet has never received points or been registered |

***

## Handling errors in code

```ts theme={null}
const res = await fetch("https://api.rewards.so/trigger", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ triggerKey, walletAddress, pointSystemId }),
});

if (!res.ok) {
  const { error } = await res.json();

  switch (res.status) {
    case 401:
      throw new Error(`Auth failed: ${error}`);
    case 403:
      // Inactive trigger or blacklisted wallet — handle gracefully
      console.warn(`Access denied: ${error}`);
      return;
    case 404:
      throw new Error(`Trigger "${triggerKey}" not configured`);
    case 429:
      const retryAfter = res.headers.get("Retry-After");
      throw new Error(`Rate limited. Retry after ${retryAfter}s`);
    default:
      throw new Error(`Unexpected error: ${error}`);
  }
}
```

***

## Rate limit details

The `429` response includes a `Retry-After` header with the number of seconds until the limit resets.

```
HTTP/1.1 429 Too Many Requests
Retry-After: 42
Content-Type: application/json

{ "error": "Rate limit exceeded. Slow down your trigger calls to prevent infinite loops." }
```

Rate limit window: **10 requests / 60 seconds** per unique `(api_key, walletAddress, triggerKey)` combination.