Maintainx Common Errors

MaintainX Common Errors

Overview

Quick reference for diagnosing and resolving common MaintainX API errors with concrete solutions and diagnostic commands.

Prerequisites

• MAINTAINX_API_KEY environment variable configured
• curl and jq available
• Access to application logs

Instructions

Step 1: Diagnostic Quick Check

Run this first to validate connectivity and auth:

# Test 1: Verify API key is valid
curl -s -o /dev/null -w "%{http_code}" \
  https://api.getmaintainx.com/v1/users?limit=1 \
  -H "Authorization: Bearer $MAINTAINX_API_KEY"
# Expected: 200

# Test 2: Check API key is set
echo "Key length: ${#MAINTAINX_API_KEY}"
# Should be > 0

# Test 3: Verify DNS resolution
nslookup api.getmaintainx.com
# Should resolve to an IP

Step 2: Identify the Error

Error Handling

400 Bad Request

Cause: Invalid request body, missing required fields, or malformed JSON.

# Diagnose: Send a minimal valid request
curl -X POST https://api.getmaintainx.com/v1/workorders \
  -H "Authorization: Bearer $MAINTAINX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Diagnostic test order"}' -v 2>&1 | tail -5

Common fixes:

• Work orders require at minimum a title field
• Priority must be one of: NONE, LOW, MEDIUM, HIGH
• Status must be one of: OPEN, IN_PROGRESS, ON_HOLD, COMPLETED, CLOSED
• Dates must be ISO 8601 format: 2026-03-19T12:00:00Z

401 Unauthorized

Cause: Missing, invalid, or expired API key.

// Diagnostic wrapper
async function diagAuth() {
  try {
    const res = await fetch('https://api.getmaintainx.com/v1/users?limit=1', {
      headers: { Authorization: `Bearer ${process.env.MAINTAINX_API_KEY}` },
    });
    if (res.status === 401) {
      console.error('API key is invalid or expired.');
      console.error('Generate a new key: MaintainX > Settings > Integrations > New Key');
    } else {
      console.log('Auth OK - status:', res.status);
    }
  } catch (e) {
    console.error('Network error:', e);
  }
}

Fixes:

• Regenerate key in MaintainX: Settings > Integrations > Generate Key
• Check for whitespace: echo "'$MAINTAINX_API_KEY'" | cat -A
• Ensure Bearer prefix (not Basic or Token)

403 Forbidden

Cause: Valid key but insufficient permissions or wrong plan tier.

Fixes:

• Verify your plan supports API access (Professional or Enterprise)
• Check user role has permission for the requested operation
• For org-specific endpoints, include X-Organization-Id header

404 Not Found

Cause: Resource ID does not exist or wrong endpoint path.

# Verify a resource exists before referencing it
curl -s "https://api.getmaintainx.com/v1/workorders/99999" \
  -H "Authorization: Bearer $MAINTAINX_API_KEY" | jq '.message // .title'

Fixes:

• Confirm the ID exists (GET the resource first)
• Use api.getmaintainx.com/v1 (not /v2 or missing version)
• Check for typos in endpoint path (/workorders not /work-orders)

422 Unprocessable Entity

Cause: Request is syntactically valid but semantically incorrect.

Common triggers:

• Invalid status transition (e.g., CLOSED to IN_PROGRESS)
• Referencing a non-existent assetId or locationId
• Invalid enum values for priority or category fields

429 Too Many Requests

Cause: Rate limit exceeded.

// Auto-retry on 429
async function safeRequest(fn: () => Promise<any>, retries = 3) {
  for (let i = 0; i <= retries; i++) {
    try {
      return await fn();
    } catch (err: any) {
      if (err?.response?.status === 429 && i < retries) {
        const wait = parseInt(err.response.headers['retry-after'] || '5') * 1000;
        console.warn(`Rate limited. Waiting ${wait}ms...`);
        await new Promise(r => setTimeout(r, wait));
      } else {
        throw err;
      }
    }
  }
}

Fixes:

• Honor the Retry-After response header
• Implement exponential backoff (see maintainx-rate-limits)
• Reduce polling frequency; use webhooks instead

500 Internal Server Error

Cause: MaintainX server-side issue.

Fixes:

• Check MaintainX Status Page
• Retry with exponential backoff (transient errors resolve themselves)
• If persistent, contact MaintainX support with request details

Output

• Identified error root cause from HTTP status code and response body
• Applied the appropriate fix from the reference above
• Verified resolution with the diagnostic quick check commands

Resources

• MaintainX API Reference
• MaintainX Status Page
• MaintainX Help Center

Next Steps

For comprehensive debugging, see maintainx-debug-bundle.

Examples

Full diagnostic script:

#!/bin/bash
echo "=== MaintainX API Diagnostics ==="
echo "Key set: $([ -n "$MAINTAINX_API_KEY" ] && echo 'YES' || echo 'NO')"
echo "Key length: ${#MAINTAINX_API_KEY}"

STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  https://api.getmaintainx.com/v1/users?limit=1 \
  -H "Authorization: Bearer $MAINTAINX_API_KEY")
echo "Auth status: $STATUS"

if [ "$STATUS" = "200" ]; then
  WO_COUNT=$(curl -s "https://api.getmaintainx.com/v1/workorders?limit=1" \
    -H "Authorization: Bearer $MAINTAINX_API_KEY" | jq '.workOrders | length')
  echo "Work orders accessible: $WO_COUNT"
fi

Source: jeremylongshore/claude-code-plugins-plus-skills → skills/.curated/maintainx-common-errors/SKILL.md

Also appears in: jeremylongshore/claude-code-plugins-plus-skills/plugins/saas-packs/maintainx-pack/skills/maintainx-common-errors/SKILL.md