--- name: maintainx-common-errors description: 'Debug and resolve common MaintainX API errors. Use when encountering API errors, authentication issues, or unexpected responses from the MaintainX API. Trigger with phrases like "maintainx error", "maintainx 401", "maintainx api problem", "maintainx not working", "debug maintainx". ' allowed-tools: Read, Write, Edit, Bash(curl:*), Grep version: 1.11.0 license: MIT author: Jeremy Longshore tags: - saas - maintainx - api - debugging - authentication compatibility: Designed for Claude Code --- # 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: ```bash # 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. ```bash # 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. ```typescript // 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. ```bash # 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. ```typescript // Auto-retry on 429 async function safeRequest(fn: () => Promise, 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](https://status.getmaintainx.com) - 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](https://status.getmaintainx.com) - [MaintainX Help Center](https://help.getmaintainx.com) ## Next Steps For comprehensive debugging, see `maintainx-debug-bundle`. ## Examples **Full diagnostic script**: ```bash #!/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 attribution: jeremylongshore Original project: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/ab85a061f7bcc039dac13ee193de7a4cd4388571/plugins/saas-packs/maintainx-pack/skills/maintainx-common-errors/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2025 Jeremy Longshore Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: jeremylongshore Original project: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/ab85a061f7bcc039dac13ee193de7a4cd4388571/plugins/saas-packs/maintainx-pack/skills/maintainx-common-errors/SKILL.md Attribution basis: Source repository record Fields of work: Development & Engineering, Sales, Customer Support Roles: Backend Developer, Customer Success Manager, Technical Support Specialties: API, Backend, Design, Frontend, Testing Tools: Maintainx Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 06f0e81cfde90974d3c720a3effb9d730137f15f70985d65e290c62bda7e7b7b