# Errors

## Overview

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

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