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 a JSON response with "error": true and an HTTP 401 Unauthorized status code.

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
• 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.