API Errors

The NeoSpace AI API uses conventional HTTP status codes to indicate the success or failure of a request. Generally, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g., a required parameter is missing), and codes in the 5xx range indicate an error with NeoSpace AI servers.

Error Response Structure

All error responses include a JSON object with the following attributes:

{
  "error": {
    "type": "invalid_request_error",
    "message": "Required parameter 'messages' missing",
    "code": "missing_param",
    "param": "messages",
    "status": 400,
    "request_id": "req_1a2b3c4d5e6f"
  }
}

Attribute	Description
type	The type of error returned
message	A human-readable message explaining the error
code	An application-specific error code
param	The specific parameter that caused the error (when applicable)
status	The HTTP status code
request_id	Unique request ID for support reference

Error Types

NeoSpace AI returns the following error types:

authentication_error

Indicates failures related to authentication, such as invalid or expired API keys.

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key provided",
    "code": "invalid_api_key",
    "status": 401,
    "request_id": "req_1a2b3c4d5e6f"
  }
}

invalid_request_error

Indicates that the request could not be processed due to invalid or missing parameters.

{
  "error": {
    "type": "invalid_request_error",
    "message": "The value of 'temperature' must be between 0 and 1",
    "code": "invalid_param_value",
    "param": "temperature",
    "status": 400,
    "request_id": "req_1a2b3c4d5e6f"
  }
}

rate_limit_error

Indicates that the request was rejected due to exceeded rate limits.

{
  "error": {
    "type": "rate_limit_error",
    "message": "Request limit exceeded. Try again in 30 seconds.",
    "code": "rate_limit_exceeded",
    "status": 429,
    "request_id": "req_1a2b3c4d5e6f"
  }
}

api_error

Indicates an internal server error.

{
  "error": {
    "type": "api_error",
    "message": "Internal server error",
    "code": "internal_server_error",
    "status": 500,
    "request_id": "req_1a2b3c4d5e6f"
  }
}

model_error

Indicates a specific AI model error during processing.

{
  "error": {
    "type": "model_error",
    "message": "The model could not process the provided input",
    "code": "model_processing_error",
    "status": 422,
    "request_id": "req_1a2b3c4d5e6f"
  }
}

HTTP Status Codes

Code	Description
200 - OK	Everything worked as expected
400 - Bad Request	The request was malformed or contains invalid parameters
401 - Unauthorized	Authentication required or authentication failed
403 - Forbidden	The API key doesn't have permission to perform the operation
404 - Not Found	The requested resource doesn't exist
422 - Unprocessable Entity	The model couldn't process the input
429 - Too Many Requests	Rate limit exceeded
500, 502, 503, 504 - Server Errors	Something went wrong on NeoSpace AI's server

Error Handling

We recommend implementing robust error handling in your application to deal with different types of errors that may occur:

try {
  const response = await fetch('https://api.neospace.ai/v1/chats', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      messages: [{ role: 'user', content: 'Hello' }],
      model: 'neo-financial-1'
    })
  });
  
  const data = await response.json();
  
  if (!response.ok) {
    // Handle error based on type
    switch (data.error.type) {
      case 'authentication_error':
        console.error('Authentication error:', data.error.message);
        // Renew token or redirect to login
        break;
      case 'rate_limit_error':
        console.error('Rate limit exceeded:', data.error.message);
        // Implement exponential backoff
        break;
      default:
        console.error('API error:', data.error.message);
    }
    return;
  }
  
  // Process successful response
  console.log(data);
} catch (error) {
  console.error('Network error:', error);
}

Common Errors and Solutions

Error	Possible Cause	Solution
invalid_api_key	Incorrect or expired API key	Verify that the key is correct and still valid
missing_param	Required parameter not provided	Add the missing parameter to the request
invalid_param_value	Parameter value outside allowed range	Adjust the value to be within acceptable limits
rate_limit_exceeded	Too many requests in a short period	Implement exponential backoff and limit request rate
model_processing_error	Input that the model cannot process	Simplify or reformulate the input

Support Requests

When contacting NeoSpace AI support about errors, always include the request_id from the error response to help our team diagnose the issue more quickly.