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:

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

error · object · required

Container for error details.

code · string · required

A machine-readable error identifier, e.g. invalid_request.

message · string · required

A human-readable description of what went wrong.

details · array

Optional list of field-level validation errors.

request_id · string · required

Unique identifier for the request. Include this when contacting support.

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.

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.

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 page for header details.

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');
}