> ## Documentation Index
> Fetch the complete documentation index at: https://docs.everybite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Codes

> Complete reference for SmartMenu API error codes

Complete reference for all SmartMenu API error codes and how to handle them.

## Error Response Format

All errors follow the standard GraphQL error format:

```json theme={null}
{
  "data": null,
  "errors": [
    {
      "message": "Human-readable error message",
      "extensions": {
        "code": "ERROR_CODE",
        "field": "optional_field_name",
        "details": {}
      },
      "path": ["query", "field"],
      "locations": [{ "line": 1, "column": 1 }]
    }
  ]
}
```

***

## Authentication Errors

### MISSING\_HEADER

**HTTP Status:** 400 Bad Request

A required header was not included in the request.

```json theme={null}
{
  "message": "Missing required header: X-Session-ID",
  "extensions": {
    "code": "MISSING_HEADER",
    "field": "X-Session-ID"
  }
}
```

**Required Headers:**

* `Authorization` - API key
* `Content-Type` - `application/json`
* `X-Session-ID` - Session identifier from `startSession`

**Resolution:** Include all required headers in your request.

***

### INVALID\_TOKEN

**HTTP Status:** 401 Unauthorized

The API key is invalid, malformed, or expired.

```json theme={null}
{
  "message": "API key is invalid or expired",
  "extensions": {
    "code": "INVALID_TOKEN"
  }
}
```

**Common Causes:**

* Typo in the API key
* Using staging key with production endpoint (or vice versa)
* Key has been revoked
* Key has expired

**Resolution:** Verify your API key is correct and matches your environment.

***

### FORBIDDEN

**HTTP Status:** 403 Forbidden

The API key doesn't have permission for the requested operation.

```json theme={null}
{
  "message": "API key does not have access to chain: other-chain",
  "extensions": {
    "code": "FORBIDDEN",
    "chainId": "other-chain"
  }
}
```

**Common Causes:**

* Accessing a chain not assigned to your partner account
* Attempting admin operations with a read-only key

**Resolution:** Contact EveryBite to request access to additional chains.

***

## Validation Errors

### INVALID\_INPUT

**HTTP Status:** 400 Bad Request

A request parameter is malformed or invalid.

```json theme={null}
{
  "message": "Invalid input: calorieRange.max must be positive",
  "extensions": {
    "code": "INVALID_INPUT",
    "field": "calorieRange.max",
    "value": -100
  }
}
```

**Common Causes:**

* Negative values for ranges
* Invalid enum values
* Missing required fields
* Malformed JSON

**Resolution:** Check the request format against the API documentation.

***

### CHAIN\_NOT\_FOUND

**HTTP Status:** 404 Not Found

The specified chain ID doesn't exist.

```json theme={null}
{
  "message": "Chain not found: invalid-chain-id",
  "extensions": {
    "code": "CHAIN_NOT_FOUND",
    "chainId": "invalid-chain-id"
  }
}
```

**Resolution:** Verify the chain ID is correct. Contact EveryBite if you believe the chain should exist.

***

### DISH\_NOT\_FOUND

**HTTP Status:** 404 Not Found

The specified dish ID doesn't exist or is no longer available.

```json theme={null}
{
  "message": "Dish not found: dish_invalid",
  "extensions": {
    "code": "DISH_NOT_FOUND",
    "dishId": "dish_invalid"
  }
}
```

**Common Causes:**

* Dish has been removed from the menu
* Incorrect dish ID
* Using EveryBite ID when partner ID expected (or vice versa)

**Resolution:** Handle gracefully in your UI. Display "Item no longer available."

***

### RESTAURANT\_NOT\_FOUND

**HTTP Status:** 404 Not Found

The specified restaurant/location ID doesn't exist.

```json theme={null}
{
  "message": "Restaurant not found: loc_invalid",
  "extensions": {
    "code": "RESTAURANT_NOT_FOUND",
    "restaurantId": "loc_invalid"
  }
}
```

**Resolution:** Verify the restaurant ID matches your ordering system.

***

## Rate Limiting

### RATE\_LIMITED

**HTTP Status:** 429 Too Many Requests

You've exceeded your rate limit.

```json theme={null}
{
  "message": "Rate limit exceeded. Please wait before retrying.",
  "extensions": {
    "code": "RATE_LIMITED",
    "retryAfter": 5,
    "limit": 1000,
    "remaining": 0,
    "reset": 1705665600
  }
}
```

**Response Headers:**

```http theme={null}
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705665600
Retry-After: 5
```

**Resolution:** Wait for the `retryAfter` seconds before retrying. Consider implementing request batching or caching filter options.

***

## Server Errors

### INTERNAL\_ERROR

**HTTP Status:** 500 Internal Server Error

An unexpected error occurred on the server.

```json theme={null}
{
  "message": "An unexpected error occurred. Please try again.",
  "extensions": {
    "code": "INTERNAL_ERROR",
    "requestId": "req_abc123"
  }
}
```

**Resolution:** Retry with exponential backoff. If the error persists, contact support with the `requestId`.

***

### SERVICE\_UNAVAILABLE

**HTTP Status:** 503 Service Unavailable

The service is temporarily unavailable.

```json theme={null}
{
  "message": "Service temporarily unavailable. Please try again later.",
  "extensions": {
    "code": "SERVICE_UNAVAILABLE"
  }
}
```

**Common Causes:**

* Planned maintenance
* Temporary overload
* Dependency failure

**Resolution:** Retry with exponential backoff. Check [status.everybite.com](https://status.everybite.com) for service status.

***

## Data Errors

### NUTRITION\_NOT\_AVAILABLE

**HTTP Status:** 200 (partial response)

Nutrition data is not available for a dish. This is not an error per se, but the `nutrition` field will be `null`.

```json theme={null}
{
  "data": {
    "dish": {
      "id": "dish_001",
      "name": "New Special",
      "nutrition": null
    }
  }
}
```

**Resolution:** Handle gracefully in your UI. Display "Nutrition information not available."

***

### MATCH\_NOT\_POSSIBLE

**HTTP Status:** 200 (informational)

The dish cannot be matched due to missing data.

```json theme={null}
{
  "data": {
    "dish": {
      "matchStatus": "NOT_MATCH",
      "matchReasons": ["Nutrition data unavailable"]
    }
  }
}
```

**Resolution:** Display the dish but indicate nutrition is unavailable.

***

## Error Handling Quick Reference

| Code                  | HTTP | Retry? | User Message              |
| --------------------- | ---- | ------ | ------------------------- |
| `MISSING_HEADER`      | 400  | No     | Fix code                  |
| `INVALID_TOKEN`       | 401  | No     | Check API key             |
| `FORBIDDEN`           | 403  | No     | Contact support           |
| `INVALID_INPUT`       | 400  | No     | Fix request               |
| `CHAIN_NOT_FOUND`     | 404  | No     | Check chain ID            |
| `DISH_NOT_FOUND`      | 404  | No     | "Item unavailable"        |
| `RATE_LIMITED`        | 429  | Yes    | "Please wait..."          |
| `INTERNAL_ERROR`      | 500  | Yes    | "Try again"               |
| `SERVICE_UNAVAILABLE` | 503  | Yes    | "Temporarily unavailable" |

***

## Support

If you encounter persistent errors:

1. Note the `requestId` from the error response
2. Check [status.everybite.com](https://status.everybite.com) for outages
3. Contact [api-partnerships@everybite.com](mailto:api-partnerships@everybite.com) with:
   * Error code and message
   * Request ID
   * Timestamp
   * Request details (redact sensitive data)