Error Handling - SpurtCommerce

Errors should be predictable for API clients while keeping internal details private.

Client handling

Inspect the actual response shape and status mapping in the deployed release. Common HTTP meanings include:

Status	General meaning	Client action
400	Invalid request	Correct payload and validation errors
401	Missing/invalid authentication	Re-authenticate
403	Authenticated but not permitted	Check role, permission, ownership, and tenant
404	Route/resource not found	Check URL, identifier, edition, and visibility
409	State/uniqueness conflict	Refresh state; do not blindly retry
413	Request too large	Reduce payload or adjust approved limits
415	Unsupported media type	Use the expected content type
429	Rate limit	Back off according to policy
5xx	Server/provider failure	Retry only when operation is safe and idempotent

Server-side rules

Return safe, actionable messages and stable error identifiers where implemented. Do not expose stack traces, SQL, secrets, filesystem paths, or provider credentials. Log diagnostic details with a request/correlation ID and redact personal/payment data.

Retry guidance

GET requests are generally safer to retry than writes. For payment, order, and webhook operations, use idempotency controls before retrying.