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 · uri

URI reference to error documentation

titlestring

Short, consistent error summary

statusinteger

HTTP status code

detailstring

Human-readable explanation

codestring

Machine-readable error slug. This is the field clients should branch on. The URI in type documents the code. New codes can be added: handle an unknown code by its HTTP status.

errorsarray of object

List of validation errors

Show properties

fieldstring

Name of the invalid field

detailstring

Field-specific error message

400

Bad Request

Bad request - invalid parameters

400 · application/problem+json

{
  "type": "https://developers.firsty.app/errors/validation_failed",
  "code": "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",
  "code": "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",
  "code": "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",
  "code": "not_found",
  "title": "Not found",
  "status": 404,
  "detail": "Package 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",
  "code": "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",
  "code": "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

Unprocessable Entity

Request cannot be applied to the current resource

422 · application/problem+json

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

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",
  "code": "idempotency_key_reused",
  "title": "Unprocessable entity",
  "status": 422,
  "detail": "This idempotency key was already used with a different request body."
}

How to handle this error

429

Too Many Requests

Rate limit exceeded. A `429` can also arrive without these headers or this body; handle it by its status code.

429 · application/problem+json

{
  "type": "https://developers.firsty.app/errors/rate_limit_exceeded",
  "code": "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",
  "code": "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/bad_gateway",
  "code": "bad_gateway",
  "title": "Bad gateway",
  "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",
  "code": "service_unavailable",
  "title": "Service unavailable",
  "status": 503,
  "detail": "This eSIM is being reconfigured. Retry in a few moments."
}

How to handle this error