Errors

Authentication Errors

Authentication errors occur when you make a request without a valid Bearer token or API key in the Authorization header. When authentication fails, the API returns an HTTP 401 Unauthorized status code with the JSON body {"success": false, "message": "unauthorized"}.

A 401 can also mean your key is fine and a token limit was reached. That response keeps the same status and a readable message, and adds fields your client can act on without parsing it: error_code (DAILY_TOKEN_LIMIT or MONTHLY_TOKEN_LIMIT), limit_type and upgrade_url. It also carries the x-tokens-* balance headers, with x-tokens-cost at 0 because nothing was charged.

{
  "success": false,
  "error_code": "DAILY_TOKEN_LIMIT",
  "limit_type": "daily",
  "upgrade_url": "https://guavy.com/app/upgrade",
  "message": "You've reached your daily token limit. To increase your daily cap, upgrade your plan at https://guavy.com/app/upgrade"
}

HTTP Response Codes

The Guavy API uses standard HTTP response codes to indicate the success or failure of an API request. Here are some common response codes you may encounter:

• 400 Bad Request - A malformed request. Most commonly a strategy path segment outside the supported set (aggressive or conservative); the response names the offending value.
• 401 Unauthorized - Missing or invalid Bearer token in the Authorization header, or your token budget is exhausted until the next reset. A budget refusal carries an error_code, so the two can be told apart
• 402 Payment Required - Market not included in your entitlement. You should not see this today: every live market is reachable on the free Sandbox tier
• 404 Not Found - The requested endpoint or resource does not exist, or the market you asked for is not one we serve yet. A market that is coming but not live says so, and lists the markets that are
• 422 Unprocessable Entity - The request was well-formed but contains invalid data or parameters
• 429 Too Many Requests - Rate limit exceeded, retry after the time specified in the response headers
• 503 Service Unavailable - A data source we depend on is temporarily unavailable — the trade-simulator upstream, or the datastore behind the trend endpoints. Your request was valid; retry after the Retry-After interval. Tokens charged for a 503 are credited back, less a 1-token floor.

We don't bill you for our failures. When a request fails on our side — a 503 from the upstream provider, or a resource that turns out not to exist (404) after we've already charged — the tokens are credited back to your budget, less a 1-token floor that keeps a failing call from being infinitely free. A malformed request on your side (400) is charged normally.