Troubleshooting

Common issues and how to fix them.

Authentication errors

"Missing or invalid API key"

Status code: 401

Your request is missing the Authorization header or the key format is wrong.

Checklist:

• The header must be Authorization: Bearer tb_... (note the Bearer prefix)
• The key format is tb_ followed by 32 hex characters, like tb_550e8400e29b41d4a716446655440000
• Make sure there are no extra spaces or newline characters in the key
• Check that you're not accidentally using a different environment variable

# Wrong - missing Bearer prefix
-H "Authorization: tb_your_key"

# Wrong - missing header entirely
curl -X POST https://www.toolbox-kit.com/api/v1/json-format -d '{}'

# Correct
-H "Authorization: Bearer tb_your_key"

"API key not registered for Pro"

You've generated a key but haven't linked it to your Pro subscription yet. Register it:

curl -X POST https://www.toolbox-kit.com/api/v1/register-key \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "tb_your_api_key_here",
    "subscriptionId": "YOUR_SUBSCRIPTION_ID",
    "provider": "dodo"
  }'

Rate limiting

"Rate limit exceeded"

Status code: 429

You've sent too many requests in the current window.

Tier	Limit
Free	100 requests / minute
Pro	1,000 requests / minute

How to handle it:

1. Check the X-RateLimit-Reset header for the Unix timestamp when the window resets
2. Wait until that time before retrying
3. Implement exponential backoff in your code

if (res.status === 429) {
  const resetAt = Number(res.headers.get('X-RateLimit-Reset'));
  const waitMs = Math.max((resetAt * 1000) - Date.now(), 1000);
  await new Promise(r => setTimeout(r, waitMs));
  // retry the request
}

Prevention tips:

• Cache responses when possible - if you're formatting the same JSON repeatedly, store the result
• Use the X-RateLimit-Remaining header to slow down before hitting the limit
• For batch work, add a small delay between requests

CORS issues

"Access-Control-Allow-Origin" errors in the browser

The ToolBox API includes CORS headers for browser requests. If you're seeing CORS errors:

• Make sure you're using the correct base URL: https://www.toolbox-kit.com/api/v1/
• Check that you're sending Content-Type: application/json in the request headers
• If you're using a custom proxy, make sure it forwards the CORS headers from the API response

Note: If you're calling the API from a server-side application (Node.js, Python, etc.), CORS doesn't apply. CORS is a browser-only security mechanism.

Preflight request fails

Browsers send an OPTIONS preflight request before the actual POST. If the preflight fails, the real request never fires. This usually means a network issue or proxy misconfiguration, not a problem with the API itself.

Common error codes

Status	Error	Cause	Fix
400	"Missing required field: X"	A required parameter is missing from the request body	Check the endpoint docs for required fields
400	"Invalid JSON"	The request body isn't valid JSON	Validate your JSON before sending. Check for trailing commas, unquoted keys, etc.
401	"Missing or invalid API key"	No Authorization header or bad key format	Add Authorization: Bearer tb_... header
429	"Rate limit exceeded"	Too many requests in the current window	Wait and retry. See rate limiting section above
500	"Internal server error"	Something broke on the server side	Retry after a short delay. If it persists, the API may be down

FAQ

Can I use the API from localhost during development?

Yes. The API accepts requests from any origin. Just make sure you're including the Authorization header.

Do I need to register my API key before using it?

You can make requests with an unregistered key, but you'll be limited to the free tier rate limit (100 requests/minute). Register your key with your Pro subscription to unlock 1,000 requests/minute.

Why am I getting empty responses?

Check that:

1. You're sending a POST request (not GET) to endpoint URLs
2. The Content-Type header is set to application/json
3. The request body is valid JSON with the correct field names

My request works in cURL but fails in my app

Common causes:

• Missing Content-Type header - some HTTP libraries don't set this automatically for JSON
• Request body not serialized - make sure you're calling JSON.stringify() (JS) or using json= parameter (Python requests)
• Environment variable not loaded - print your API key to verify it's being read correctly (then remove the print statement)

Is there a status page?

Yes. Check toolbox-kit.com/status for current API availability.