maintainx-common-errors

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 <[e-mail]>
tags	["saas","maintainx","api","debugging","authentication"]
compatibility	Designed for Claude Code, also compatible with Codex and OpenClaw

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