Skip to main content
All errors return a consistent JSON structure: 
{
  "error": {
    "code": "AGENT_NOT_FOUND",
    "message": "No agent found with the specified ID.",
    "request_id": "req_abc123",
    "docs_url": "https://docs.imarobot.ai/errors/AGENT_NOT_FOUND"
  }
}

​
Error codes

CodeHTTPWhen
UNAUTHORIZED401Missing or invalid API key or JWT
FORBIDDEN403Valid auth but insufficient permissions
AGENT_NOT_FOUND404Agent ID does not exist
TOKEN_INVALID422Token present but fails cryptographic validation
TOKEN_EXPIRED422Token signature valid but expiry has passed
TOKEN_REVOKED422Token valid but agent has been revoked
RATE_LIMIT_EXCEEDED429Caller exceeded their rate limit tier
VALIDATION_ERROR400Request body missing required fields or malformed
INTERNAL_ERROR500Unexpected server error — always logged, never exposes stack traces

​
Handling errors

const result = await verifier.verify(token);

if (!result.valid) {
  switch (result.error) {
    case 'TOKEN_REVOKED':
      // Agent has been explicitly revoked — reject permanently
      return res.status(403).json({ error: 'Agent revoked' });
    case 'TOKEN_EXPIRED':
      // Token expired — agent should issue a new one
      return res.status(401).json({ error: 'Token expired' });
    case 'TOKEN_INVALID':
      // Malformed or tampered token — reject
      return res.status(401).json({ error: 'Invalid token' });
  }
}