Error Handling

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

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 API key
403	Forbidden	No permission to perform this operation
404	Not Found	Requested resource does not exist
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side internal error

Error Response Format

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Parameter 'name' cannot be empty",
    "details": {}
  }
}

Common Error Codes

Error Code	HTTP Status	Description
UNAUTHORIZED	401	API key is invalid or expired
FORBIDDEN	403	No permission to access this resource
NOT_FOUND	404	Resource does not exist
INVALID_PARAMETER	400	Invalid request parameter
RATE_LIMIT_EXCEEDED	429	Request rate limit exceeded
INTERNAL_ERROR	500	Internal server error
INSUFFICIENT_TOKENS	402	Insufficient Token balance

Error Handling Recommendations

1. Check the status code: Determine whether the request was successful based on the HTTP status code
2. Parse the error message: Read error.message in the response body for the specific reason
3. Retry strategy: Implement backoff retries for 429 and 5xx errors
4. Logging: Record error information for troubleshooting

Related Documentation

• API Authentication — Authentication methods
• API Endpoints — Available endpoint list