Error Codes

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.

Response Format

When an authentication or flywheel error occurs, the API returns a 4xx HTTP status code along with a JSON response containing the error code and a descriptive message. Example:

{
  "error": "ERR_KEY_SCOPES_UNAUTHORIZED",
  "message": "The provided API key doesn't have the required 'burn' scope to access this endpoint"
}

Example flywheel error:

{
  "error": "ERR_FLYWHEEL_PIPELINE_TOO_BIG",
  "message": "Pipeline contains too many actions to fit in a single transaction"
}

API Documentation

Flywheel V1

Tokenomics (Deprecated)

Authentication Error Codes

Flywheel-Specific Error Codes

Pipeline and Action Error Codes

Response Format

​Authentication Error Codes

​Flywheel-Specific Error Codes

​Pipeline and Action Error Codes

​Response Format

Authentication Error Codes

Flywheel-Specific Error Codes

Pipeline and Action Error Codes

Response Format