Error Handling

HTTP errors

Our API follows a predictable HTTP error code format:

• 400 - invalid_request_error: The request was malformed or had invalid parameters (e.g., invalid model name, missing required fields, request validation errors).
• 401 - authentication_error: No valid API key was provided or the token is not associated with a valid user.
• 404 - not_found_error: The requested resource doesn’t exist (e.g., model not found).
• 500 - server_error: Something went wrong on CompactifAI’s servers. These are generally temporary issues that should be retried.

Error shapes

Errors are always returned as JSON, with a top-level error object that includes type, message, and optionally param and code values. The API uses a consistent error format across all endpoints:

{
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid request: Model 'nonexistent-model' not found; available: [model1, model2]",
    "param": null,
    "code": null
  }
}

Error Properties

Property	Description
type	The type of error returned (always present)
message	A human-readable message providing more details about the error
param	The parameter that caused the error (currently always null in our implementation)
code	A machine-readable error code (currently always null in our implementation)

Common Error Scenarios

Authentication Errors (401)

Authentication errors occur when:

• No Bearer token is provided in the Authorization header
• The provided token is not in a valid format
• The token is not associated with a valid user in our system

{
  "detail": "Token is not associated with a valid user"
}

Model Not Found (400/404)

When requesting a model that doesn’t exist:

• Returns 404 for path parameter validation (e.g., /models/{invalid-model})
• Returns 400 for request body validation (e.g., invalid model in chat completion request)

{
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid request: Model 'invalid-model' not found; available: [available-model-1, available-model-2]",
    "param": null,
    "code": null
  }
}

Request Validation Errors (400)

Our API automatically validates request bodies and returns 400 errors for malformed requests:

• Missing required fields
• Invalid data types
• Values outside allowed ranges

Server Errors (500)

Internal server errors return a generic error message:

{
  "detail": "Unexpected server error"
}

API status

You can check the current status of our API at status.compactif.ai.