7.41HTTP status mapping

An API should return meaningful status codes.

Typical thinking:

bad JSON/request
→ 400

authentication missing/invalid
→ 401

authenticated but forbidden
→ 403

customer not found
→ 404

business conflict
→ 409

Salesforce temporarily unavailable
→ 503

downstream timeout
→ possibly 504

unexpected application failure
→ 500

Your organization may define its own standards.

Important:

Don't expose every downstream 500 as your own arbitrary 500 without understanding semantics.