# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.something.cool/rewards-claiming/errors.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.