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, resets_at and upgrade_url. resets_at is when the limit lifts, in UTC: the next midnight for the daily limit, and for the monthly budget the 1st of the month on a free account or the renewal of a monthly subscription once its payment clears. It is null when that time cannot be stated. 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",
  "resets_at": "2026-10-16T00:00:00Z",
  "upgrade_url": "https://guavy.com/app/upgrade",
  "message": "You've reached your daily token limit. It resets at 00:00 UTC. For a higher daily cap, choose a 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: a missing or invalid Bearer token in the Authorization header, or a token budget that is spent until the next reset. A budget refusal carries an error_code, so the two can be told apart.
• 402 Payment Required: the market is not included in your plan. 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 live.
• 429 Too Many Requests: the rate limit was exceeded. Retry after the interval in the Retry-After header.
• 503 Service Unavailable: a data source we depend on is temporarily unavailable: the trade-simulator upstream, or the datastore behind the news, sentiment and 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, such as a 503 from a data source or a 404 for a resource that turns out not to exist 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.