Skip to main content

​
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"
}
FieldTypeDescription
messagestringHuman-readable error message
codestringMachine-readable error code
suggestionstring?Recovery hint for agents
retryableboolean?Whether retry with backoff might succeed
detailsobject?Structured details (e.g., Zod validation issues)
requestIdstring?Correlation ID for support

​
Common Error Codes

HTTPCodeMeaning
400VALIDATION_FAILEDRequest body failed schema validation
401UNAUTHORIZEDMissing or invalid authentication
401INVALID_API_KEYAPI key not found or revoked
403FORBIDDENInsufficient permissions or scope
404NOT_FOUNDResource does not exist
409CONFLICTIdempotency key reused with different body
409ALREADY_REVOKEDAPI key already revoked
410VERSION_SUNSETAPI version has been removed
429RATE_LIMITEDToo many requests
500INTERNAL_ERRORServer error

​
Best Practices

  1. Check retryable — if true, retry with exponential backoff
  2. Read suggestion — it tells agents exactly how to fix the issue
  3. Log requestId — include it when contacting support
  4. Handle code programmatically — don’t parse message strings