Agent skill · data analytics · jeremylongshore
maintainx-common-errors
Debug and resolve common MaintainX API errors.
Why this skill is useful
Provides specific diagnostic commands and error handling patterns for the MaintainX API that the AI wouldn't reliably generate on its own.
What it needs
Requires curl, jq installed locally. Requires maintainx account access. About 3k tokens when loaded. Last updated 2026-08-07. 2,604 stars on the source repository.
What this skill does
MaintainX Common Errors Overview Quick reference for diagnosing and resolving common MaintainX API errors with concrete solutions and diagnostic commands. Prerequisites MAINTAINXAPIKEY 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: Step 2: Identify the Error Error Handling 400 Bad Request Cause: Invalid request body, missing required fields, or malformed JSON. 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, INPROGRESS, ONHOLD, COMPLETED, CLOSED Dates must be ISO 8601 format: 2026-03-19T12:00:00Z 401 Unauthorized Cause: Missing, invalid, or expired API key. Fixes: Regenerate key in MaintainX: Settings > Integrations > Generate Key Check for whitespace: echo "'$MAINTAINXAPIKEY'" 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. 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 INPROGRESS) Referencing a non-existent assetId or locationId Invalid enum values for priority or category fields 429 Too Many Requests Cause: Rate limit exceeded. 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. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills jeremylongshore/maintainx-common-errors--54877d