API errors
API errors
Every Partners API error is an RFC 9457 problem document whose type field links to one of these pages. Each page explains what the error means and how to handle it.
400bad_requestThe request was malformed or a parameter had a value the endpoint cannot act on.400validation_failedOne or more fields failed validation. The `errors` array lists each field and what is wrong with it.401unauthorizedThe request carried no usable credentials: the bearer token is missing, invalid or expired, or the client credentials were rejected.402payment_requiredYour account balance with Firsty is below the minimum this operation requires.403feature_not_enabledThis feature is not enabled for your credentials.403forbiddenThe credentials are valid, but this operation is not allowed. The `detail` field says why.404balance_not_foundThe eSIM's balance has not been set up yet.404esim_not_foundThe eSIM in the request does not exist under the profile in the URL.404not_foundThe resource in the request URL does not exist for your credentials.404number_registration_not_foundThis eSIM has no number registration.404port_in_not_foundThe port-in request in the URL does not exist on this eSIM.404profile_not_foundThe profile in the request URL does not exist for your credentials.404scheduled_action_not_foundThe scheduled action in the request URL does not exist on this subscription.404subscription_not_foundThe subscription in the request URL does not exist on this profile.404subscription_plan_not_foundThe subscription plan does not exist for your credentials.404webhook_endpoint_not_foundThe webhook endpoint in the request URL does not exist for your credentials.409balance_not_availableThe eSIM's balance does not exist until the eSIM is activated.409balance_update_pendingAnother update of this eSIM's balance is still being applied.409concurrent_modificationThe resource changed while the request ran.409conflictThe request is valid but conflicts with the current state of the resource. The `detail` field says which conflict you hit.409esim_change_pendingAn earlier change to the eSIM is still in progress.409esim_not_activeThe operation needs an active eSIM, and this one is not active yet.409esim_not_provisionedThe eSIM is not set up on its network yet, so the operation cannot run on it.409esim_suspendedA suspended eSIM cannot be swapped.409esim_swap_cooldownThe eSIM was activated less than an hour ago, and cannot be swapped until it has been live for an hour.409esim_swap_pendingThe eSIM is being swapped, and the request has to wait until the swap completes.409esim_terminatedThe eSIM is terminated, so no further lifecycle operation, swap or package order is possible.409invalid_state_transitionThe resource's current state does not allow this operation.409limit_reachedA limit for your account has been reached.409no_esim_availableNo eSIM is available to swap into right now.409number_registration_pendingA registration of this number is already with the registry.409port_in_pendingA number port-in on the eSIM is still in progress.409services_change_pendingAn earlier change of the eSIM's services is still in progress.409services_not_availableThe eSIM's services cannot be read or changed until the eSIM exists on its network.422balance_not_supportedThe eSIM does not support a prepaid balance.422balance_operation_not_supportedThis eSIM's balance accepts credits only.422balance_update_refusedThe network refused the balance update.422client_transaction_id_reusedThis `clientTransactionId` was already used with a different update.422esim_variant_not_allowedThe eSIM cannot be swapped into the eSIM variant the request names.422esim_variant_not_swappableThe eSIM cannot be swapped.422idempotency_key_reusedThis `X-Idempotency-Key` was already used with a different request body.422insufficient_balanceThe eSIM's balance is too low for this debit.422number_not_availableThe eSIM has no phone number to register yet.422number_registration_not_supportedNumber registration is not available for the declared country.422port_in_cancel_refusedThe network refused to cancel the port-in.422porting_not_supportedNumber porting is not available for this eSIM.422services_change_refusedThe network refuses this combination of services.422services_not_changeableA requested service is not offered on this eSIM, or cannot be switched.422services_not_supportedThis eSIM's network offers no services to read or change.422sim_refused_by_networkThe network refused to activate the selected SIM.422unprocessable_entityThe request is well formed and valid, but the operation it asks for cannot be carried out. The `detail` field explains why.423lockedA request with the same `X-Idempotency-Key` is still being processed. Wait briefly, then retry with the same key.429rate_limit_exceededToo many requests in the current window. Wait for the time in `Retry-After`, then try again.500internal_errorSomething failed on Firsty's side. The request may or may not have taken effect, so check the resource's state before trying again.502bad_gatewayA network the request depends on failed to complete it.503service_unavailableThe request cannot be served right now. Wait a moment, then retry.