​
What it means

Something on our side failed in a way we didn’t anticipate. We never leak internal details in detail — but every 500 is logged with full context, and the instance field matches the X-Request-Id header so we can find the exact request in our logs.

​
What to do

  1. Retry with exponential backoff. 500-class responses are typically transient. Start at 1 second, double up to a cap of 30 seconds, give up after ~5 attempts.
  2. Keep the X-Request-Id. If the error persists, send it to admin@digitalseaservice.com. We can pull the exact request in seconds.
  3. Check status.digitalseaservice.com before raising — if we’re in an incident, you’re not alone and we’re already on it.
  4. Don’t surface the raw error to end users. The instance is for your engineers. Show users a generic “Couldn’t reach Digital Sea Service — please retry in a moment” message.

​
Idempotency

All V1 endpoints are read-only (GET), so retrying a 500 is always safe. When we add write endpoints in V2 they’ll require explicit idempotency keys — until then, just retry.