⚠️Error Handling

The Fuul API uses standard HTTP status codes to indicate success or failure. The SDK catches API errors and throws typed error classes for common failure modes.

HTTP status codes

Status	Meaning
200	Success
400	Bad Request — invalid parameters or validation error
401	Unauthorized — missing or invalid API key
403	Forbidden — API key lacks required permissions
404	Not Found
409	Conflict — duplicate resource
429	Too Many Requests — rate limit exceeded
500	Server Error

SDK error types

The SDK throws these error classes for affiliate code operations. Each extends Error and sets a .name property:

Error class	.name	When thrown
ValidationError	'ValidationError'	Invalid characters in the code. Has an errors: string[] property with details.
InvalidSignatureError	'InvalidSignatureError'	Signature doesn't match the address and message
AddressInUseError	'AddressInUseError'	Address already has a code registered. Has an address property.
CodeInUseError	'CodeInUseError'	Code is already taken. Has a code property.

These are exported from @fuul/sdk and can be used with instanceof:

import { Fuul, CodeInUseError, AddressInUseError, ValidationError, InvalidSignatureError } from '@fuul/sdk';

try {
  await Fuul.createAffiliateCode({
    userIdentifier: '0x1234...',
    identifierType: 'evm_address',
    signature: '0xabc...',
    code: 'my-code',
  });
} catch (error) {
  if (error instanceof CodeInUseError) {
    // Code already taken — prompt the user to choose another
    console.log('Taken code:', error.code);
  } else if (error instanceof AddressInUseError) {
    // Address already has a code
    console.log('Address:', error.address);
  } else if (error instanceof ValidationError) {
    // Invalid code format
    console.log('Validation errors:', error.errors);
  } else if (error instanceof InvalidSignatureError) {
    // Signature verification failed
  } else {
    // Unexpected error
    console.error('Unexpected error:', error);
  }
}

For API calls not related to affiliate codes, the SDK throws standard Error objects with the API error message.

API key permissions reference

Endpoint category	Required key type
Read data (leaderboards, rewards, conversions)	Any key type
Send tracking events (pageview, connect_wallet)	send:tracking_event or higher
Send trigger events (custom offchain events)	send:trigger_event
Manage audiences, webhooks, set referrers	service_role

For full details on key types, see API Key Management.