Error Codes

All NEXUS API errors follow a consistent format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": {}
  }
}

Error Code Reference

Error Classes

NEXUS defines typed error classes in @nexus-protocol/shared:

import {
  NexusError,
  AgentNotFoundError,
  TaskNotFoundError,
  UnauthorizedError,
  ForbiddenError,
  ValidationError,
  InsufficientCreditsError,
  RateLimitError,
  AgentEndpointError,
  TaskTimeoutError,
} from '@nexus-protocol/shared';

NexusError (base class)

class NexusError extends Error {
  code: NexusErrorCode;
  statusCode: number;
  details?: Record<string, unknown>;

  toJSON(): { error: { code: string; message: string; details?: object } };
}

Handling Errors in the SDK

The SDK throws NexusError instances on API failures:

import { NexusClient } from '@nexus-protocol/sdk';

const client = new NexusClient({ apiKey: 'nxk_...' });

try {
  const agent = await client.agents.get('invalid-uuid');
} catch (err) {
  if (err instanceof NexusError) {
    console.error(`Error ${err.code}: ${err.message}`);
    console.error(`HTTP Status: ${err.statusCode}`);
  }
}

Retry-Safe Errors

The SDK automatically retries on these status codes:

• 429 — Rate limit exceeded
• 502 — Bad gateway
• 503 — Service unavailable
• 504 — Gateway timeout

Non-retryable errors (400, 401, 403, 404) are thrown immediately.

Rate Limiting

Rate limits are enforced per-IP using a sliding window:

When rate-limited, the response includes:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "details": {
      "retryAfter": 30
    }
  }
}

JSON-RPC Error Codes

For A2A protocol errors (used in /api/v1/a2a):