Design a model API error contract

An API error is part of the interface. Clients need to distinguish invalid input from unavailable service and unexpected failure without parsing a stack trace. Define stable status codes and response fields, then test them.

Success and validation failure

The local lab wraps its schema and prediction function in a framework-neutral endpoint contract.

from deployment_cases import error_contract_case

result = error_contract_case()
assert result["success"]["status"] == 200
assert result["invalid"]["status"] == 422
assert result["stable_error_keys"] == ["code", "fields", "message", "request_id"]
print(result["invalid"]["body"])

Negative tenure returns status 422 with code SCHEMA_VALIDATION, a safe message, field tenure_months and request ID REQ-422. It does not call the model or return internal paths.

Separate error families

Define contracts for malformed JSON, schema failure, payload too large, authentication/authorization, rate limit, dependency unavailable, model unavailable and internal error. Decide which failures a client may retry. Validation is generally not fixed by blind retries; transient service failure may be.

Include a stable machine-readable code and human-readable message. Keep request IDs unique. Do not expose stack traces, secrets, raw model paths or private training information. Log detailed diagnostics under controlled access, with sensitive fields minimized.

Test behavior and observability

Contract tests should verify status, keys and safe messages. Operational metrics should count errors by stable code and model version. Alert on unexpected failure rates, while avoiding an alert storm for a known client sending invalid data.

Version breaking contract changes and communicate them before removing fields. The Data Science course connects robust error handling with model reliability and handover.

Exercise

Add MODEL_UNAVAILABLE and PAYLOAD_TOO_LARGE responses with retry guidance. Test that no stack trace or raw payload appears and that metrics reconcile with response counts.

Continue learning

This article is part of the Model deployment and MLOps sequence. Use the neighbouring tasks when you need the prerequisite or the next application.

• Review the prerequisite or neighbouring task in Package preprocessing with the trained model.
• Continue with Version a model and its training data together.

Reference: HTTP Semantics status codes.