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 configuredcurl and jq available- Access to application logs
Instructions
Step 1: Diagnostic Quick Check
Run this first to validate connectivity and auth:
curl -s -o /dev/null -w "%{http_code}" \
https://api.getmaintainx.com/v1/users?limit=1 \
-H "Authorization: Bearer $MAINTAINX_API_KEY"
echo "Key length: ${#MAINTAINX_API_KEY}"
nslookup api.getmaintainx.com
Step 2: Identify the Error
Error Handling
400 Bad Request
Cause: Invalid request body, missing required fields, or malformed JSON.
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.
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.
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.
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
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
