Response Structure

Response Structure

The Testing API follows a consistent JSON response format for all endpoints. This ensures predictable integration and simplifies error handling for developers using the Supervised AI platform.

Standard Success Response

All successful requests return a JSON object containing a status indicator, an optional message, and the requested data.

{
  "status": "success",
  "message": "Operation completed successfully.",
  "data": {
    "id": "test_72619",
    "type": "unit_test",
    "attributes": {
      "name": "Validation Logic",
      "result": "passed"
    }
  },
  "meta": {
    "request_id": "req_882910",
    "timestamp": "2023-10-27T10:00:00Z"
  }
}

Standard Error Response

When a request fails, the API returns a structured error object and an appropriate HTTP status code. This allows for programmatic error parsing and debugging.

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The provided parameters are invalid.",
    "details": [
      {
        "field": "test_id",
        "issue": "Field is required"
      }
    ]
  },
  "meta": {
    "request_id": "req_882911",
    "timestamp": "2023-10-27T10:05:00Z"
  }
}

Response Fields

| Field | Type | Description | | :--- | :--- | :--- | | status | string | Indicates the outcome of the request. Always success or error. | | message | string | A human-readable summary of the response or action taken. | | data | object/array | The primary payload of the response. Omitted in some error cases. | | error | object | Contains detailed error information (only present if status is error). | | error.code | string | A machine-readable string identifying the error type. | | meta | object | Metadata about the request, such as pagination or request tracking IDs. |

HTTP Status Codes

The Testing API uses standard HTTP response codes to indicate the success or failure of an API request.

Success Codes (2xx)

• 200 OK: The request was successful and the data is included in the body.
• 201 Created: The request was successful and a new resource (e.g., a test case) was created.
• 204 No Content: The request was successful, but there is no content to return (common for DELETE).

Client Error Codes (4xx)

• 400 Bad Request: The request was unacceptable, often due to missing a required parameter or invalid JSON.
• 401 Unauthorized: No valid API key provided.
• 403 Forbidden: The API key does not have permissions to perform the request.
• 404 Not Found: The requested resource does not exist.
• 429 Too Many Requests: Rate limit exceeded.

Server Error Codes (5xx)

• 500 Internal Server Error: Something went wrong on our end.
• 503 Service Unavailable: The server is temporarily unable to handle the request (e.g., during maintenance).