> ## Documentation Index
> Fetch the complete documentation index at: https://moonshadow-ep3.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Moonshadow API Error Codes and Troubleshooting

> Complete reference for Moonshadow API error codes, HTTP status codes, error response shape, and recommended actions for each error type.

Moonshadow returns structured error responses for every failed request. Understanding the error format, status codes, and recommended fixes helps you debug integration issues quickly and build reliable retry logic.

## Error Response Shape

Every error response follows a consistent JSON structure:

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "The request body contains malformed JSON.",
    "details": [
      {
        "field": "name",
        "issue": "must be a string"
      }
    ],
    "request_id": "req_8f2a1b3c4d5e6f7g"
  }
}
```

<ResponseField name="error" type="object" required>
  Container for error details.

  <ResponseField name="code" type="string" required>
    A machine-readable error identifier, e.g. `invalid_request`.
  </ResponseField>

  <ResponseField name="message" type="string" required>
    A human-readable description of what went wrong.
  </ResponseField>

  <ResponseField name="details" type="array">
    Optional list of field-level validation errors.
  </ResponseField>

  <ResponseField name="request_id" type="string" required>
    Unique identifier for the request. Include this when contacting support.
  </ResponseField>
</ResponseField>

## HTTP Status Codes

| Status | Code                   | Meaning                                                                         | What To Do                                                                                                                        |
| ------ | ---------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| 400    | `invalid_request`      | The request is malformed or missing required fields.                            | Check the request body and query parameters against the API docs. Inspect the `details` array for field-level issues.             |
| 401    | `unauthorized`         | The API key is missing, invalid, or revoked.                                    | Verify your Bearer token in the `Authorization` header. Regenerate the key in your workspace dashboard if needed.                 |
| 403    | `forbidden`            | The API key lacks permission for this resource or action.                       | Check the workspace member's role and the endpoint's required scopes. Only admins can manage workspace settings and billing.      |
| 404    | `not_found`            | The requested resource does not exist.                                          | Confirm the resource ID and workspace context. IDs are scoped per workspace, so verify you are targeting the correct workspace.   |
| 409    | `conflict`             | The request conflicts with the current state, such as a duplicate unique field. | Retry with corrected state, for example a different name or email. Use idempotency keys for write operations to avoid duplicates. |
| 422    | `unprocessable_entity` | The request is syntactically valid but semantically invalid.                    | Check business rules, such as trying to connect an integration that is already active, or assigning a role that does not exist.   |
| 429    | `rate_limited`         | You have exceeded the rate limit of 1,000 requests per minute per workspace.    | Read the `Retry-After` header and wait before retrying. Implement exponential backoff. See the Rate Limits page for details.      |
| 500    | `internal_error`       | An unexpected error occurred on Moonshadow's side.                              | Retry the request after a brief wait. If the error persists, contact support with the `request_id`.                               |
| 503    | `service_unavailable`  | Moonshadow is temporarily unavailable, usually during maintenance.              | Wait and retry. Check the status page for reported incidents.                                                                     |

<Warning>
  429 responses indicate you have hit the 1,000 requests per minute per workspace limit. Continued requests without pausing can lead to longer blocks. Always respect the `Retry-After` header and implement backoff.
</Warning>

## Retry Guidance

Build resilient integrations with the following retry strategy:

1. **Do not retry 400, 401, 403, 404, 409, or 422.** Fix the request and try again.
2. **Retry 429, 500, and 503 with exponential backoff.** Start with a 1-second delay, double on each retry, and cap at 60 seconds.
3. **Respect headers.** Use `Retry-After` for 429 and `X-RateLimit-Reset` to schedule your next call. See the [Rate Limits](/reference/rate-limits) page for header details.

```javascript theme={null}
async function moonshadowFetch(url, options, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const res = await fetch(url, options);
    if (res.ok) return res;

    if (res.status === 429 || res.status >= 500) {
      const delay = Math.min(1000 * Math.pow(2, i), 60000);
      const retryAfter = res.headers.get('Retry-After');
      await sleep(retryAfter ? retryAfter * 1000 : delay);
      continue;
    }

    throw new Error(`Moonshadow error ${res.status}: ${await res.text()}`);
  }
  throw new Error('Max retries exceeded');
}
```