Error Handling

All NexSpace API errors return a consistent JSON structure with machine-readable codes and agent-friendly recovery hints.

Error Format

{
  "error": {
    "message": "Human-readable description",
    "code": "MACHINE_CODE",
    "suggestion": "How to fix this — designed for LLM agents to self-correct",
    "retryable": false,
    "details": {}
  },
  "requestId": "req_abc123"
}

Field	Type	Description
`message`	string	Human-readable error message
`code`	string	Machine-readable error code
`suggestion`	string?	Recovery hint for agents
`retryable`	boolean?	Whether retry with backoff might succeed
`details`	object?	Structured details (e.g., Zod validation issues)
`requestId`	string?	Correlation ID to quote when reporting an issue

Common Error Codes

HTTP	Code	Meaning	`retryable`
400	`VALIDATION_FAILED` / `VALIDATION_ERROR`	Request body failed schema validation	`false`
400	`IDEMPOTENCY_KEY_TOO_LONG`	`Idempotency-Key` exceeds 255 characters	`false`
401	`UNAUTHENTICATED`	Missing authentication	`false`
401	`API_KEY_REQUIRED`	Endpoint requires an API key (not a session/JWT), or the credential is org-only and not bound to a user	`false`
401	`INVALID_API_KEY`	API key not found, revoked, or expired	`false`
401	`USER_INACTIVE`	The account behind the credential is deactivated	`false`
403	`INSUFFICIENT_SCOPE`	API key/token lacks a required scope	`false`
403	`IP_NOT_ALLOWED`	Request IP is not in the key’s allowlist	`false`
403	`FORBIDDEN`	Insufficient permissions	`false`
403	`SELF_APPROVAL_FORBIDDEN`	You own the run that raised the approval but lack the `ai.approve_actions` permission	`false`
404	`NOT_FOUND`	Resource does not exist	`false`
409	`IDEMPOTENCY_CONFLICT`	Idempotency key reused with a different body	`false`
409	`ALREADY_RESOLVED`	The approval was already approved or rejected; `details.status` carries which	`false`
409	`ALREADY_REVOKED`	API key already revoked	`false`
410	`VERSION_SUNSET`	API version has been removed	`false`
429	`API_KEY_RATE_LIMITED`	Per-key rate limit exceeded	`true`

When retryable is omitted, infer it from the status: 429, 503, 408, 502, and 504 are retryable; other 4xx are not.

There is no INTERNAL_ERROR code. No 5xx response carries that code — the constant does not exist anywhere in the server. A 500 gives you a message, a top-level requestId, and a timestamp:

{
  "error": {
    "message": "Internal server error"
  },
  "requestId": "5f1c8d0e-2b7a-4f31-9c6e-0a3b8d47e912",
  "timestamp": "2026-01-14T18:22:05.417Z"
}

error.code is present only when the underlying thrown error carried its own code property (a driver or library error code, for example) — it is never a stable NexSpace error constant on a 500, so do not branch on it.Detect server errors by HTTP status, not by code. An agent branching on code === 'INTERNAL_ERROR' will never match. retryable is also absent on a 500 (it is only inferred for 408, 429, 502, 503, 504 and the 4xx range), so treat a 500 as retry-once-with-backoff on status alone and log the requestId.

Codes you will hit on the headless surfaces

IDEMPOTENCY_KEY_TOO_LONG — the REST Idempotency-Key middleware rejects any key over 255 characters before your handler runs. See Idempotency.
API_KEY_REQUIRED on /api/agents/{id}/runs… — the credential authenticated but is org-only (no bound user). Agent runs execute as a user, so every route on that surface refuses. Use a PAT or a user-bound key/OAuth token.
SELF_APPROVAL_FORBIDDEN / ALREADY_RESOLVED — from POST /api/approvals/{id}/{approve,reject}. See Agent Runs → Approvals.

Errors over MCP

MCP does not use the codes above. Everything on this page is the REST contract. Over MCP the failure is a JSON-RPC error whose code is a negative integer (-32602, -32003, -32009, -32000, …), not one of the SCREAMING_SNAKE strings — and the HTTP status is 200 even when the call failed. The exceptions are the ones rejected before dispatch: 401 (authentication), 429 (rate limit), and 404 (unknown stream id). Check response.error, not the status. See the MCP error-code table for the authoritative list.

Tool calls to the MCP server return errors two ways:

Protocol errors (unknown tool, bad params, insufficient scope) come back as a JSON-RPC error object. The error.data carries suggestion and retryable, mirroring the REST contract.
Execution failures (the tool ran but failed) come back as a normal tools/call result with isError: true. The content[].text payload includes the failure message followed by a Suggestion: line so the calling model can self-correct.

Best Practices

Check retryable — if true, retry with exponential backoff; if false, reformulate the request instead of retrying
Read suggestion — it tells agents exactly how to fix the issue
Log requestId — include it when you email admin@nexspace365.com
Handle code programmatically — don’t parse message strings

Getting Started

Core Concepts

Integrations

Reference

Error Handling

Error Handling

Error Format

Common Error Codes

Codes you will hit on the headless surfaces

Errors over MCP

Best Practices

​Error Handling

​Error Format

​Common Error Codes

​Codes you will hit on the headless surfaces

​Errors over MCP

​Best Practices

Error Handling

Error Format

Common Error Codes

Codes you will hit on the headless surfaces

Errors over MCP

Best Practices