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

# Errors

> Learn about standardized error responses and how to interpret them.

# Error Handling

Gale returns consistent and descriptive error responses across all endpoints to help you debug and recover gracefully.

## Standard Error Format

All errors follow this format:

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "Validation failed: merchant_product_id is required.",
    "details": {
      "field_errors": {
        "merchant_product_id": ["This field is required"]
      }
    }
  }
}
```

## HTTP Status Codes

| Status Code | Error Code            | Meaning           | When It Happens                           |
| ----------- | --------------------- | ----------------- | ----------------------------------------- |
| 400         | `bad_request`         | Bad Request       | Malformed JSON or missing required fields |
| 401         | `unauthorized`        | Unauthorized      | Missing or invalid API key                |
| 403         | `forbidden`           | Forbidden         | Valid token but insufficient permissions  |
| 404         | `not_found`           | Not Found         | Resource does not exist                   |
| 409         | `conflict`            | Conflict          | Invalid state change                      |
| 422         | `validation_error`    | Validation Failed | Field validation failed                   |
| 429         | `rate_limit_exceeded` | Too Many Requests | Rate limit exceeded                       |
| 500         | `internal_error`      | Server Error      | Something went wrong on Gale's side       |

## Error Examples

### Validation Error (422)

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "details": {
      "field_errors": {
        "line_items": ["At least one line item is required"],
        "customer.email": ["Invalid email format"]
      }
    }
  }
}
```

### Unauthorized (401)

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}
```

### Not Found (404)

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Order not found"
  }
}
```

### Rate Limited (429)

```json theme={null}
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please try again in 30 seconds."
  }
}
```

Response includes `Retry-After` header indicating seconds to wait.

## Best Practices

* **Check status code first**: Use HTTP status codes to determine error type
* **Parse error details**: Check `error.details.field_errors` for specific validation failures
* **Implement retry logic**: For 429 and 500 errors, retry with exponential backoff
* **Log errors**: Store error responses for debugging

## Related

* [Authentication](/developer-manual/authentication) - API key setup
* [Rate Limits](/developer-manual/rate-limits) - Handling rate limits