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

# Errors

> Learn about the errors that can be returned by the API and how to handle them effectively.

The Moonbase API returns structured error responses with standard HTTP status codes.

## Error response format

All error responses follow a consistent JSON structure:

```json theme={null}
{
  "errors": [
    {
      "status": "400",
      "title": "Bad Request",
      "detail": "The 'email' field is required but was not provided."
    }
  ]
}
```

Each error object contains:

* `status`: The HTTP status code as a string
* `title`: A brief, human-readable summary of the error
* `detail`: A more detailed explanation of what went wrong (when available)

### Status Codes

Responses include standard HTTP status codes to indicate success or failure:

| Status Code | Title                 | Description                                                  |
| ----------- | --------------------- | ------------------------------------------------------------ |
| `400`       | Bad Request           | The request is malformed or contains invalid parameters.     |
| `401`       | Unauthorized          | Authentication failed or was not provided.                   |
| `403`       | Forbidden             | Request understood; API key lacks resource access.           |
| `404`       | Not Found             | The requested resource doesn't exist.                        |
| `409`       | Conflict              | Request conflicts with current state.                        |
| `422`       | Unprocessable Entity  | The request was well-formed but contains semantic errors.    |
| `429`       | Too Many Requests     | Too many requests in a given amount of time (rate-limiting). |
| `500`       | Internal Server Error | Server-side issues for Moonbase                              |
| `503`       | Service Unavailable   | The server is temporarily unavailable.                       |

## Response headers

All responses from the API include an `x-request-id` header. This is a unique identifier for the request. When contacting support, include this ID.

## Common error scenarios

### Authentication errors (401)

**Cause:** Missing, invalid, or expired API key

**Solution:**

* Verify API key is present in Authorization header
* Check the API key is valid in  [organization settings](https://app.moonbase.ai/settings/api_keys)
* Regenerate if the key may have been compromised

### Rate limiting errors (429)

**Cause:** Too many requests sent in a short time period

**Solution:**

* Implement exponential backoff retry logic
* Space out requests to stay within rate limits
* See the [rate limiting guide](/api-reference/rate-limiting) for detailed information

### Validation errors (422)

**Cause:** Request data fails validation rules

**Solution:**

* Check the `detail` field in the error response for specific validation messages
* Verify required fields are included
* Ensure field values meet format and length requirements

### Server errors (500, 503)

**Cause:** Temporary server-side issues for Moonbase

**Solution:**

* Retry the request after a brief delay
* If the problem persists, contact support with the `x-request-id` from the API response
* Implement error handling

## Best practices

* **Log error details**: Capture both the status code and error message for debugging
* **Include request IDs**: Log the `x-request-id` header for support requests
* **Validate locally first**: Check required fields and formats before making API calls
* **Implement error handling**: Handle all response scenarios