> ## 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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.