Errors

Overview

The API uses standardized error codes to help you identify and troubleshoot issues. All error responses follow this format:

{
  "status": "error",
  "code": "ERROR_CODE",
  "message": "Human-readable error message",
  "errors": [ ... ] // Optional array of validation errors
}

HTTP Status Codes

HTTP Status	Description
400	Bad Request - The request was invalid
401	Unauthorized - Authentication is required or failed
404	Not Found - The requested resource was not found
409	Conflict - The request conflicts with the current state
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Something went wrong on our end

Error Codes

Validation Errors (400)

Error Code	Description	Possible Solution
VALIDATION_ERROR	Generic validation error	Check the errors array for specific field validation issues
INVALID_ADDRESS	Invalid Solana address format	Ensure the address is a valid Solana public key
INVALID_TOKEN_ADDRESS	Invalid token address format	Ensure the token address is a valid Solana token mint address
INVALID_CLAIM_TYPE	Invalid claim type	Claim type must be either "TOKEN" or "SOL"
INVALID_SIGNATURE	Invalid transaction signature format	Ensure the signature is in the correct format

Authentication Errors (401)

Error Code	Description	Possible Solution
MISSING_AUTHENTICATION	Missing signature or timestamp headers	Include both X-Signature and X-Timestamp headers
INVALID_SIGNATURE	Signature verification failed	Ensure the signature matches the timestamp and is from the correct wallet
EXPIRED_SIGNATURE	Timestamp is older than 5 minutes	Generate a new timestamp and signature
INVALID_TIMESTAMP	Timestamp is not a valid number	Ensure the timestamp is a valid Unix timestamp in milliseconds
SIGNATURE_VERIFICATION_ERROR	Error during signature verification	Check that the signature is properly encoded in base58 format

Resource Errors (404)

Error Code	Description	Possible Solution
TOKEN_NOT_FOUND	Token not found or no rewards available	Verify the token address or check if any rewards are available
CLAIM_NOT_FOUND	Claim transaction not found	Verify the transaction signature

Logical Errors (400-409)

Error Code	Description	Possible Solution
CLAIM_ERROR	Generic claim error	Check the error message for more details
CLAIM_IN_PROGRESS	A claim for this token is already in progress	Wait for the existing claim to complete or expire
CLAIM_EXPIRED	Claim transaction has expired	Initiate a new claim
CLAIM_FAILED	Claim transaction failed during processing	Check the error message and blockchain explorer for details

Service Limits (429)

Error Code	Description	Possible Solution
RATE_LIMIT_EXCEEDED	Too many requests	Slow down your request rate and try again later

Error Handling Best Practices

1. Always check the error code, not just the HTTP status

2. Implement exponential backoff for retrying rate-limited requests

3. Display human-readable error messages to your users

4. Log detailed error information for debugging

5. Handle common errors gracefully in your UI