Errors

Every error is an RFC 9457 problem document with the application/problem+json content type. These shared responses can occur on any endpoint.

Error shape

typestring · urirequired

URI reference to error documentation

titlestringrequired

Short, consistent error summary

statusintegerrequired

HTTP status code

detailstringrequired

Human-readable explanation

errorsarray of objectrequired

List of validation errors

Show properties

fieldstringrequired

Name of the invalid field

detailstringrequired

Field-specific error message

400

Bad Request

Bad request - invalid parameters

400 · application/problem+json

{
  "type": "https://developers.firsty.app/errors/validation-failed",
  "title": "Validation failed",
  "status": 400,
  "detail": "Request contains invalid fields",
  "errors": [
    {
      "field": "planReference",
      "detail": "Must be a valid 14-character plan reference"
    }
  ]
}

How to handle this error

401

Unauthorized

Unauthorized - missing or invalid API key

401 · application/problem+json

{
  "type": "https://developers.firsty.app/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing bearer token"
}

How to handle this error

403

Forbidden

Forbidden - client does not have access to this resource

403 · application/problem+json

{
  "type": "https://developers.firsty.app/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "You do not have access to this eSIM"
}

How to handle this error

404

Not Found

Resource not found

404 · application/problem+json

{
  "type": "https://developers.firsty.app/errors/not-found",
  "title": "Not found",
  "status": 404,
  "detail": "eSIM not found"
}

How to handle this error

409

Operation Conflict

Another operation is already in progress

409 · application/problem+json

{
  "type": "https://developers.firsty.app/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "Another balance update for this eSIM is still in flight"
}

How to handle this error

409

Conflict

Request with this idempotency key is still being processed

409 · application/problem+json

{
  "type": "https://developers.firsty.app/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "A request with this idempotency key is already being processed. Please retry later."
}

How to handle this error

422

Idempotency Key Reused

Idempotency key was previously used with a different request body

422 · application/problem+json

{
  "type": "https://developers.firsty.app/errors/idempotency-key-reused",
  "title": "Idempotency key reused",
  "status": 422,
  "detail": "This idempotency key was already used with a different request body."
}

How to handle this error

422

Unprocessable Entity

Request cannot be applied to the current resource

422 · application/problem+json

{
  "type": "https://developers.firsty.app/errors/unprocessable-entity",
  "title": "Unprocessable entity",
  "status": 422,
  "detail": "Request cannot be applied"
}

How to handle this error

429

Too Many Requests

Rate limit exceeded

429 · application/problem+json

{
  "type": "https://developers.firsty.app/errors/rate-limit-exceeded",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "Too many requests. Please retry later."
}

How to handle this error

500

Internal Server Error

Internal server error

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 this error

502

Bad Gateway

Temporary service failure

502 · application/problem+json

{
  "type": "https://developers.firsty.app/errors/internal-error",
  "title": "Internal server error",
  "status": 502,
  "detail": "Unable to complete the request"
}

How to handle this error

503

Service Unavailable

Service temporarily unavailable. Safe to retry.

503 · application/problem+json

{
  "type": "https://developers.firsty.app/errors/service-unavailable",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "This eSIM is being reconfigured. Retry in a few moments."
}

How to handle this error