Error Handling

The GeniSpace API uses standard HTTP status codes to indicate request results and provides a flat error body in the response.

HTTP Status Codes

Status Code	Meaning	Description
`200`	Success	Request processed normally
`201`	Created	Resource created successfully
`400`	Bad Request	Invalid or missing request parameters
`401`	Unauthorized	Missing or invalid credentials
`402`	Payment Required	Insufficient token balance or quota
`403`	Forbidden	No permission to perform this operation
`404`	Not Found	Requested resource does not exist
`429`	Too Many Requests	Daily token usage limit exceeded
`500`	Internal Server Error	Server-side internal error

The error body is flat — message and code sit at the top level alongside success: false. There is no nested error object.

{
  "success": false,
  "message": "Validation failed: name cannot be empty",
  "code": "VALIDATION_ERROR"
}

Validation failures may additionally include an errors array with field-level detail.

Error Code	HTTP Status	Description
`VALIDATION_ERROR`	400	Invalid request parameter (express-validator failure)
`BAD_REQUEST`	400	Malformed request
`UNAUTHORIZED`	401	Credentials are invalid or expired
`PAYMENT_ERROR`	400	Payment or billing failure
`FORBIDDEN`	403	No permission to access this resource
`NOT_FOUND`	404	Resource does not exist
`SERVER_ERROR`	500	Internal server error

When a request cannot be served because of token balance or quota constraints, the API returns one of the following:

Error Code	HTTP Status	Description
`INSUFFICIENT_TOKENS`	402	Token balance is depleted
`BELOW_MINIMUM_BALANCE`	402	Balance is below the minimum required for the operation
`REQUEST_TOO_LARGE`	400	Request payload exceeds the per-request token limit
`DAILY_LIMIT_EXCEEDED`	429	Daily token usage limit reached

Check the status code: Determine whether the request was successful based on the HTTP status code
Parse the error message: Read the top-level message and branch on code for the specific reason
Retry strategy: Implement backoff retries for 429 and 5xx errors
Handle billing errors: Treat 402 responses as a signal to top up the space's token balance
Logging: Record error information for troubleshooting