API errors

Internal server error

Something failed on Firsty's side. The request may or may not have taken effect, so verify state before re-attempting.

500502503application/problem+json

What it means

The request was valid but the platform failed to process it. This is not your integration's fault, and on a 500 the outcome is genuinely unknown: the operation may have completed just before the failure, or not started at all.

The same type arrives as 502 or 503 when the failure sits with an upstream carrier or provisioning system, such as an eSIM that is mid-reconfiguration. Those are transient; a short wait and a retry usually succeeds.

500 · application/problem+json

{
  "type": "https://developers.firsty.app/errors/internal-error",
  "title": "Internal server error",
  "status": 500,
  "detail": "An unexpected error occurred"
}

How to handle it

For reads, retry with exponential backoff and jitter. Most of these failures are transient.
For a POST or PATCH, retry once with the same X-Idempotency-Key. That can never run the operation twice: it returns the outcome the API recorded for the original attempt, this error included.
If the same key keeps returning this error, check the resource's state with a read before re-attempting with a fresh key, so an operation that did complete is not repeated.
If the error persists, contact Firsty support with the X-Request-Id response header value and the time of the request. That id lets us find the failing call in our logs.

Idempotency, in the rate limits guide Errors reference

What it means

How to handle it

Related