Guides
Error Handling
Error codes, responses, and retry strategies
Error Handling
MCP-level errors
Tool responses include a status field that indicates success or failure:
| Status | Meaning | Billed? |
|---|---|---|
"ok" / "found" | Successful response with data | Yes |
"error" | Something went wrong (see message) | No |
"not_found" | Restaurant or area not in database | No |
"no_coverage" | Area exists but has insufficient data | No |
Error response format
{
"status": "error",
"message": "Descriptive error message"
}HTTP-level errors
| Code | Meaning | Example message | Retry? |
|---|---|---|---|
| 200 | Success (check status in response body) | -- | -- |
| 401 | Invalid or missing API key | "Missing or invalid API key. Expected Authorization: Bearer sk_seemor_..." | No |
| 401 | Revoked key | "API key has been revoked." | No |
| 429 | Per-minute rate limit | "Rate limit exceeded. Try again in a moment." | Yes, after a few seconds |
| 429 | Daily rate limit | "Daily API limit exceeded. Resets in 24 hours." | Yes, next day |
| 500 | Server error | -- | Yes, with backoff |
Tier access errors
If a free key attempts to call a paid tool, the response is returned as an MCP tool result (HTTP 200) with:
{
"status": "error",
"message": "This API key is on the free tier. This tool requires a paid plan. Request an upgrade at app.seemor.ai/developer or contact ryan@larracoslabs.com."
}This applies to:
lookup_restaurantwithfields: "standard"or"premium"ask_about_restaurantrecommend
Common errors and resolutions
| Error | Cause | Fix |
|---|---|---|
"Restaurant data is loading. Please try again in a moment." | Server cache warming after restart | Wait 30 seconds and retry |
"No restaurant found with ID..." | Invalid restaurant_id | Verify the ID via find_restaurant first |
"Rate limit exceeded..." | Too many requests | Wait and retry, or request higher limits |
"This API key is on the free tier..." | Calling a paid tool with a free key | Request an upgrade |
"No restaurant coverage in {city}..." | recommend called for uncovered area | Check coverage with explore_area first |
Retry strategy
- Do retry: 500 errors (use exponential backoff: 1s, 2s, 4s, max 3 retries), "data is loading" errors
- Do not retry: 401 (fix your key), 429 daily limit (wait for reset), 400 (fix your request)
- Do not retry: MCP-level
not_foundorno_coverage(these won't change with retries)