Practice: Error Bodies for Four Failures

An unknown product, two invalid fields, a rate limit and a database outage; write each response and say whether to retry.

Designing errors means choosing the status, the type, the detail and what to leave out, then telling the client whether to retry. For each failure of POST /orders, write the status code and a problem details body, and say whether the client should retry.

The product code pen-gold does not exist.
The quantity is 0 and the delivery date is in the past.
The client has sent 100 requests this minute, its limit.
The database is down, and the driver threw an exception naming the host db-primary.internal.

Show the answers

text

1. 422  {"type": ".../problems/unknown-product",
         "title": "Unknown product", "status": 422,
         "detail": "No product has the code pen-gold."}
   Retry: no; fix the product code.

2. 422  {"type": ".../problems/validation",
         "title": "The request has invalid fields", "status": 422,
         "errors": [
           {"pointer": "#/items/0/quantity", "detail": "must be at least 1"},
           {"pointer": "#/deliverOn", "detail": "must be in the future"}]}
   Retry: no; fix both fields.

3. 429  Retry-After: 30
        {"type": ".../problems/rate-limited",
         "title": "Too many requests", "status": 429,
         "detail": "The limit is 100 requests a minute."}
   Retry: yes, after 30 seconds.

4. 503  Retry-After: 60
        {"type": "about:blank", "title": "Service Unavailable",
         "status": 503, "instance": "urn:request:7d21e0"}
   Retry: only with an idempotency key; the host name stays in the logs.

Four illustrative problem details responses

The unknown product could also be a 404 if products are addressed by path; in a body field, 422 says which value failed. A 500 is also fair for the outage; 503 with Retry-After tells the client the failure is temporary.

← → move through sections and cards