API Documentation
Error Codes
Error Codes reference
Authentication Error Codes
The API returns specific error codes when authentication-related issues occur. These codes help identify the exact nature of the problem so that you can take appropriate action.| Error Code | Description |
|---|---|
ERR_UNAUTHORIZED | General authentication failure. This error occurs when your request lacks valid authentication credentials or the provided credentials are invalid. Check that you’re including your API key in the x-believe-api-key header and that the key is active. |
ERR_DUPLICATE_IDEMPOTENCY_KEY | A request with the same X-Idempotency-Key header value has already been processed successfully. This prevents duplicate operations. If you receive this error, it means your original request was successful, and you should retrieve the original response rather than retrying with the same idempotency key. |
ERR_KEY_SCOPES_UNAUTHORIZED | The API key used for the request doesn’t have the required scope permissions for the requested operation. For example, a key without the burn scope cannot access flywheel burn actions. Check your API key’s scope assignments and request the appropriate scopes for your intended operations. |
Flywheel-Specific Error Codes
These error codes are specific to Flywheel API operations:| Error Code | Description |
|---|---|
ERR_KEY_ALREADY_EXISTS | An active API key already exists for this token. Only one active key per token is allowed. Revoke the existing key before creating a new one. |
ERR_TOKEN_NOT_FOUND | The specified token could not be found or does not belong to your account. Verify the token ID and ensure you have access to it. |
ERR_KEY_NOT_FOUND | The API key could not be found or is invalid. Ensure you’re using a valid, active API key for your flywheel operations. |
ERR_FLYWHEEL_NOT_FOUND | No flywheel is associated with the provided API key. Register a flywheel via the web app first before attempting batch operations. |
ERR_BATCH_NOT_FOUND | No batch exists with the provided batch ID. Verify the batch ID is correct and the batch hasn’t been deleted. |
ERR_KEY_GENERATION_FAILED | Failed to generate the API key during flywheel registration. This could be due to invalid scopes or internal errors. |
ERR_MULTISIG_WALLET_CREATION_FAILED | Failed to create the multisig wallet required for flywheel operations. This indicates an issue with the Solana blockchain or wallet service. |
ERR_FLYWHEEL_REGISTRATION_FAILED | The flywheel registration process failed after key and wallet creation. Check your request parameters and try again. |
ERR_BATCH_INIT_FAILED | Failed to compile pipelines or initialize the batch transaction. This could be due to invalid actions, transaction size limits, or compilation errors. |
ERR_BATCH_EXECUTE_FAILED | Failed to execute the batch. Check the batch status for detailed failure information and transaction results. |
ERR_BATCH_CURRENT_FAILED | Failed to retrieve current batch information. This indicates a database or service issue. |
Pipeline and Action Error Codes
These errors occur during pipeline compilation and action validation:| Error Code | Description |
|---|---|
ERR_FLYWHEEL_ACTIONS_EMPTY | One or more pipelines contain no actions. Each pipeline must have at least one action. |
ERR_FLYWHEEL_INVALID_ACTION | One or more actions in the pipelines are invalid or unsupported. Check that all action types are valid and properly formatted. |
ERR_FLYWHEEL_NO_INSTRUCTIONS | Pipeline compilation resulted in no transaction instructions. This indicates an issue with action processing. |
ERR_FLYWHEEL_PIPELINE_TOO_BIG | Pipeline contains too many actions to fit in a single Solana transaction. Reduce the number of actions or split into multiple pipelines. |
ERR_INVALID_PROOF | The proof type provided is not recognized, not permitted for the API key, or the proof object is invalid. Check your registered proof types and proof data format. |