home / skills / bankrbot / claude-plugins / bankr-error-handling

bankr-error-handling skill

safe

/bankr-agent/skills/bankr-error-handling

This skill helps diagnose Bankr API authentication and error issues, guiding setup and troubleshooting to resolve keys, tokens, and rate limits quickly.

npx playbooks add skill bankrbot/claude-plugins --skill bankr-error-handling

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.3 KB

---
name: Bankr Agent - Error Handling
description: This skill should be used when encountering authentication errors, API key errors, 401 errors, "invalid API key", "BANKR_API_KEY not set", job failures, or any Bankr API errors. Provides setup instructions and troubleshooting guidance for resolving Bankr configuration issues.
version: 1.0.0
---

# Bankr Error Handling

Resolve Bankr API errors and authentication issues.

## Authentication Errors (401)

### Symptoms
- HTTP 401 status code
- "Invalid API key" or "Unauthorized" message

### Resolution

Present these setup instructions to the user:

**Step 1: Create an API Key**
```
Visit https://bankr.bot/api to create a new API key
```

**Step 2: Set Environment Variable**
```bash
# Add to shell profile (~/.zshrc or ~/.bashrc)
export BANKR_API_KEY=bk_your_api_key_here
```

**Step 3: Restart Claude Code**
```
Close and reopen the terminal/Claude Code session
```

**Important**: Do NOT retry when authentication fails. User must fix API key first.

## Common Job Failures

| Error | Cause | Resolution |
|-------|-------|------------|
| Insufficient balance | Not enough tokens | Check balance, reduce amount |
| Token not found | Invalid symbol/address | Verify token exists on chain |
| Slippage exceeded | Price moved too much | Retry or try smaller amount |
| Transaction reverted | On-chain failure | Check transaction details |
| Rate limit exceeded | Too many requests | Wait and retry |

## HTTP Status Codes

| Code | Meaning | Action |
|------|---------|--------|
| 400 | Bad request | Check prompt format |
| 401 | Unauthorized | Fix API key (see above) |
| 402 | Payment required | Ensure wallet has BNKR on Base |
| 429 | Rate limited | Wait and retry |
| 500 | Server error | Retry after delay |

## Troubleshooting Checklist

1. **API Key**: Set, starts with `bk_`, Claude Code restarted after setting
2. **Network**: Internet working, api.bankr.bot reachable
3. **For Trading**: Wallet has sufficient balance, token exists on chain

## Reporting Errors to Users

1. State what went wrong simply
2. Provide specific fix steps
3. Avoid technical jargon
4. Suggest alternatives

**Example**:
```
Your Bankr API key is not configured. To set it up:
1. Visit https://bankr.bot/api to create an API key
2. Set BANKR_API_KEY in your environment
3. Restart Claude Code
```

Overview

This skill helps developers identify and resolve Bankr API authentication and runtime errors quickly. It focuses on 401/invalid API key issues, common job failures, HTTP status code guidance, and a concise troubleshooting checklist. Follow the setup steps to restore access and reduce downtime for Bankr-powered Web3 flows.

How this skill works

The skill inspects error messages and HTTP status codes returned by Bankr endpoints to classify the problem (authentication, rate limiting, on-chain failure, etc.). It then provides targeted remediation: how to create and set a BANKR_API_KEY, restart your environment, check balances or token metadata, and when to retry. It translates technical responses into actionable, non-technical steps.

When to use it

You receive HTTP 401, “invalid API key”, or “BANKR_API_KEY not set” errors.
An API call returns rate limit (429) or server (500) responses repeatedly.
A job fails with on-chain issues like insufficient balance or transaction reverted.
You need clear setup instructions for Bankr API key configuration.
You want a quick checklist before reporting an issue to support.

Best practices

Create an API key at https://bankr.bot/api and confirm it starts with bk_.
Set BANKR_API_KEY in your shell profile (e.g., ~/.zshrc or ~/.bashrc) and export it.
Restart your terminal or Claude Code session after setting the env var before retrying.
Do not retry requests when authentication fails; fix the API key first.
Check network reachability to api.bankr.bot and your wallet balance for trading actions.

Example use cases

Fixing a 401 Unauthorized response by creating and exporting a BANKR_API_KEY.
Diagnosing a failed swap due to insufficient balance and reducing the amount.
Recovering from rate limit errors by waiting and implementing backoff retries.
Identifying a token-not-found failure and verifying token symbol or contract address on-chain.
Responding to server errors (500) by retrying after a short delay and collecting logs.

FAQ

How do I create a Bankr API key?

Visit https://bankr.bot/api, follow the prompts to create a key, and copy the key that begins with bk_.

Where do I set the BANKR_API_KEY?

Add export BANKR_API_KEY=bk_your_api_key_here to your shell profile (~/.zshrc or ~/.bashrc) and restart your terminal or Claude Code session.