Errors

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

{ "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

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.

Overview

Endpoints

HTTP status codes

Error reference

Authentication

Triggers

Leaderboard / Activity

Wallet

Handling errors in code

Rate limit details

​HTTP status codes

​Error reference

​Authentication

​Triggers

​Leaderboard / Activity

​Wallet

​Handling errors in code

​Rate limit details

HTTP status codes

Error reference

Authentication

Triggers

Leaderboard / Activity

Wallet

Handling errors in code

Rate limit details