API errors

service_unavailable

The request cannot be served right now. Wait a moment, then retry.

503application/problem+json

What it means

The request was fine, but the resource or a network it depends on cannot serve it right now, for example while an eSIM is being reconfigured or a network is limiting its rate. When the response carries Retry-After, it gives the seconds to wait.

A retry with the same X-Idempotency-Key within 48 hours returns this same response rather than running the operation again.

503 · application/problem+json

{
  "type": "https://developers.firsty.app/errors/service_unavailable",
  "title": "Service unavailable",
  "status": 503,
  "detail": "The new eSIM is not ready yet; retry the request",
  "code": "service_unavailable"
}

How to handle it

Wait for Retry-After when present, otherwise a few seconds, and back off with jitter if it persists.
For a write, read the resource's state first, then retry with a fresh X-Idempotency-Key if the operation did not take effect.
If the condition lasts more than a few minutes, contact Firsty support with the X-Request-Id response header value.

Errors reference