Error Codes Reference

All API errors follow a consistent bilingual format. The message field is automatically localized based on the Accept-Language header.

Error Response Structure

{
  "error": {
    "code": "ERROR_CODE",
    "message": "English error message",
    "details": [
      { "path": "fieldName", "message": "Field-specific error" }
    ]
  }
}

Arabic (Accept-Language: ar):

{
  "error": {
    "code": "ERROR_CODE",
    "message": "رسالة الخطأ بالعربية",
    "details": [
      { "path": "fieldName", "message": "خطأ خاص بالحقل" }
    ]
  }
}

The details field is optional and only included for validation errors with field-level information.

---

Authentication Errors (401 / 403 / 502)

Code	Status	English Message	Arabic Message	Condition
AUTH_REQUIRED	401	Authentication required	يلزم المصادقة	Missing or invalid token
AUTH_SESSION_EXPIRED	401	Session has expired	انتهت صلاحية الجلسة	Expired JWT
AUTH_ACCOUNT_DEACTIVATED	401	Account is deactivated	الحساب معطل	Sign-in blocked at OTP verification for a deactivated account (admin deactivation or account-deletion soft-delete)
AUTH_USE_MOBILE_APP	403	This account is for the Skyte mobile app. Please sign in there.	هذا الحساب مخصص لتطبيق Skyte على الجوال. يرجى تسجيل الدخول من التطبيق.	Customer (end_user) signing in on a web client (verify-otp, magic-link)
AUTH_USE_PORTAL	403	Portal accounts sign in from the Skyte web portal.	حسابات البوابة تسجل الدخول من بوابة Skyte على الويب.	Non-end_user role signing in on a mobile client (verify-otp, magic-link)
AUTH_INVALID_OTP	401	Invalid or expired code	رمز التحقق غير صالح أو منتهي الصلاحية	Wrong code, unregistered phone/email, or no code to check (never issued, expired after 300s, or spent by 5 wrong attempts). One answer, so verification never reveals whether a code was issued
AUTH_NO_CREDENTIAL	401	At least one of phone or email is required	يلزم توفير رقم الهاتف أو البريد الإلكتروني	Neither phone nor email provided
AUTH_PHONE_EXISTS	401	Phone number already registered	رقم الهاتف مسجل مسبقاً	Duplicate phone on registration
AUTH_EMAIL_EXISTS	401	Email address already registered	البريد الإلكتروني مسجل بالفعل	Duplicate email on registration. PUT /profile and PUT /auth/me return it, with the same messages, as status 409 when another account already uses the email
AUTH_LAST_IDENTIFIER	409	Cannot remove the only sign-in identifier	لا يمكن حذف وسيلة تسجيل الدخول الوحيدة	email: null on PUT /profile or PUT /auth/me for an account with no phone
AUTH_CONSENT_REQUIRED	401	Required consent types missing	أنواع الموافقة المطلوبة ناقصة	Invalid or missing consent entries
AUTH_RATE_LIMIT_EXCEEDED	401	Too many OTP requests, please try again later	طلبات كثيرة للتحقق، يرجى المحاولة لاحقاً	Per-recipient OTP request throttle. More than 3 OTP requests were sent to the same phone or email within the 15-minute window (register or change-phone; login sends in the background and never reports it). This is separate from verification-attempt limiting, which is reported under AUTH_INVALID_OTP instead
AUTH_PHONE_UPDATE_FAILED	502	Failed to update phone number	فشل تحديث رقم الهاتف	The phone-change OTP was verified, but persisting the new phone number failed. This happens if the local database update itself fails, or if it succeeds but the following Supabase Auth update fails (the local change is then rolled back)
AUTH_BLOCKLISTED	403	User or device is blocklisted	المستخدم أو الجهاز محظور	Blocklist check
FORBIDDEN	401	Insufficient permissions — super_admin required	صلاحيات غير كافية — مطلوب super_admin	Non-super_admin on compliance routes
AUTH_FORBIDDEN	403	Insufficient permissions	صلاحيات غير كافية	Role/area guard denied the request (a role other than super_admin or admin on /admin/users, or an admin without staff-users, a user lacking the required area on an area-gated route, or a non-end_user on a customer-only route)

AUTH_INVALID_OTP is used generically for both wrong OTP and unregistered phone/email to prevent enumeration attacks.

AUTH_PHONE_EXISTS is 401 here (thrown as an AuthError on /auth/register) but 409 on /auth/change-phone and /auth/verify-change-phone (thrown there as a plain AppError) — see Authentication.

FORBIDDEN (compliance routes) is thrown as an AuthError, whose constructor only maps the exact code AUTH_FORBIDDEN to 403 — every other code, including the distinct string FORBIDDEN, resolves to 401. So despite the "super_admin required" message, this code actually returns 401, not 403.

---

Validation Errors (400)

Code	Status	English Message	Condition
VALIDATION_ERROR	400	Validation failed	Zod schema validation failed. details array contains field-specific errors.
VALIDATION_ICCID_INVALID	400	ICCID must be exactly 19 digits	ICCID format validation failed
VALIDATION_SIM_LIMIT_EXCEEDED	400	SIM limit exceeded for your identity type	CITC SIM limit per identity type exceeded

Validation Error Details Example

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      { "path": "phone", "message": "Phone must be Saudi format +966XXXXXXXXX" },
      { "path": "iccid", "message": "ICCID must contain only digits" }
    ]
  }
}

---

Not Found Errors (404)

Code	Status	English Message	Arabic Message	Condition
NOT_FOUND	404	Resource not found	المورد غير موجود	Generic not found
PACKAGE_NOT_FOUND	404	Package not found	الباقة غير موجودة	Package ID not found or inactive
ACTIVATION_NOT_FOUND	404	Activation not found	التفعيل غير موجود	Activation ID not found or not owned by user

---

Administration User Errors (403 / 404 / 409 / 502)

Returned by the /admin/users endpoints. See Admin Users.

Code	Status	English Message	Arabic Message	Condition
ADMIN_USER_SCOPE_EXCEEDED	403	This change is outside your own access.	هذا التغيير خارج نطاق صلاحياتك.	A grant beyond the caller's own levels, or a target the caller may not act on (itself, or outside its access); also POST /admin/companies/invites without Manage on the area the invite needs
ADMIN_USER_NOT_FOUND	404	Administration user not found	مستخدم الإدارة غير موجود	No manageable user with the given id (owners and end users are not manageable), or a target outside every area the caller can view
ADMIN_USER_PHONE_EXISTS	409	Phone number already registered	رقم الهاتف مسجل بالفعل	Phone already in use on create
ADMIN_USER_EMAIL_EXISTS	409	Email address already registered	البريد الإلكتروني مسجل بالفعل	Email already in use on create
ADMIN_USER_CREATE_FAILED	502	Failed to create user account	فشل إنشاء حساب المستخدم	Auth account creation failed upstream
ADMIN_USER_PROFILE_NOT_CREATED	502	Failed to create user profile	فشل إنشاء الملف الشخصي للمستخدم	Profile row was not seeded; the orphaned auth identity is rolled back
ADMIN_USER_DELETE_FAILED	502	Failed to remove user	فشل حذف المستخدم	Auth identity removal failed upstream, after the profile row was already deleted

PATCH and DELETE on a company person can also return COMPANY_LAST_ADMIN or COMPANY_ADMIN_ROLE_LOCKED — see Company Errors.

---

Officer Resend Errors (409)

Returned by the /admin/officer delivery resend routes. See Customers.

Code	Status	English Message	Arabic Message	Condition
OFFICER_RESEND_NOT_ISSUED	409	Nothing has been issued for this record yet	لم يتم إصدار أي شيء لهذا السجل بعد	The activation is not an eSIM or has no issued profile yet, or the store order has not been issued
OFFICER_RESEND_RECORD_DELETED	409	This record has been deleted	تم حذف هذا السجل	The activation or store order is soft-deleted
OFFICER_RESEND_CREDENTIALS_CLEARED	409	This order no longer holds an eSIM profile to send	لم يعد هذا الطلب يحتوي على ملف eSIM لإرساله	The store order was issued but no longer holds an eSIM profile
OFFICER_RESEND_NO_EMAIL	409	The customer has no email address	لا يوجد بريد إلكتروني مسجّل لهذا العميل	The delivery email cannot be sent without an address

---

Notification Errors

See Notifications API and notification callbacks. The shared catalogue declares ten notification errors. The routes add two service-unavailability errors and a payload-size error.

Code	Status	English Message	Arabic Message	Condition
NOTIFICATION_NOT_FOUND	404	Notification not found	الإشعار غير موجود	Inbox item is missing, foreign, or scrubbed
NOTIFICATION_BATCH_NOT_FOUND	404	Notification batch not found	دفعة الإشعارات غير موجودة	Unknown batch ID
NOTIFICATION_BATCH_NOT_CANCELLABLE	409	This notification batch can no longer be cancelled	لم يعد بالإمكان إلغاء دفعة الإشعارات هذه	Batch is running or finished
NOTIFICATION_INVALID_CUSTOM_CONTENT	400	Notification content is invalid	محتوى الإشعار غير صالح	Declared catalogue code. Current HTTP content validation returns VALIDATION_ERROR instead
NOTIFICATION_UNKNOWN_EVENT	400	Unknown notification event	حدث إشعار غير معروف	Trigger event is unknown. Current HTTP template validation returns VALIDATION_ERROR instead
NOTIFICATION_CHANNEL_DISABLED	400	This notification channel is not available	قناة الإشعارات هذه غير متاحة	Requested channel is disabled or unsupported by the template
NOTIFICATION_OPT_OUT_NOT_ALLOWED	400	This notification channel cannot be turned off	لا يمكن إيقاف قناة الإشعارات هذه	Declared catalogue code. Current HTTP opt-out validation returns VALIDATION_ERROR for in_app instead
NOTIFICATION_WEBHOOK_SIGNATURE_INVALID	401	Notification callback signature is invalid	توقيع استدعاء الإشعارات غير صالح	Callback signature is missing or invalid
NOTIFICATION_WEBHOOK_PROVIDER_UNKNOWN	404	Unknown notification callback provider	مزود استدعاء الإشعارات غير معروف	Channel or provider is unknown, lacks callback capabilities, or is a mock callback in production
PAYLOAD_TOO_LARGE	413	Notification callback payload is too large	حجم بيانات استدعاء الإشعارات أكبر من المسموح	Raw callback body exceeds the 64 KiB cap. Rejected before reading, parsing or signature handling
NOTIFICATION_IDEMPOTENCY_CONFLICT	409	This idempotency key was already used with a different request	مفتاح منع التكرار هذا مستخدم بالفعل مع طلب مختلف	Same sending administrator and unexpired key with a different validated request
SERVICE_UNAVAILABLE	503	Service unavailable	الخدمة غير متاحة	Administrative send acceptance or replay recovery failed. Retry-After: 1
NOTIFICATION_WEBHOOK_UNAVAILABLE	503	Notification callback could not be queued. Retry the same event.	تعذّر وضع استدعاء الإشعار في قائمة الانتظار. أعد إرسال الحدث نفسه.	Callback receipt, enqueue, or handoff-stamp write failed. Retry-After: 60

Protected routes also use AUTH_REQUIRED and administrative routes use AUTH_FORBIDDEN. Invalid fields use VALIDATION_ERROR. Applicable HTTP throttling returns RATE_LIMIT_EXCEEDED, including on notification callbacks.

Delivery Failure Codes

These values are durable delivery bookkeeping, not HTTP error envelopes. Batch failure lists expose them through errorCode.

Code	Condition
NOTIFICATION_PROVIDER_RETRYABLE	Provider rejected the attempt transiently
NOTIFICATION_PROVIDER_TERMINAL	Provider rejected the delivery permanently
NOTIFICATION_ATTEMPT_FAILED	Classified fallback for rendering, dispatch, or worker failure
NOTIFICATION_STALLED	Stalled recovery exhausted its allowance
NOTIFICATION_START_LIMIT	Worker exceeded the allowed number of starts

A verified terminal callback can instead record its provider-supplied reason code. Suppression reasons are account_inactive, channel_opted_out, no_address, and provider_unsupported. They are not HTTP errors. NOTIFICATION_CALLBACK_UNMATCHED is a retry signal for callback correlation, not a response code or durable delivery failure.

---

Company Errors (403 / 404 / 409 / 502)

Returned by the B2B company registration, portal, and admin-oversight endpoints. See B2B Portal and B2B Admin.

Code	Status	English Message	Arabic Message	Condition
COMPANY_NOT_FOUND	404	Company not found	الشركة غير موجودة	No company with the given id
COMPANY_ALREADY_REGISTERED	409	You already belong to a company	أنت مرتبط بشركة بالفعل	Caller already has a company membership
COMPANY_CR_EXISTS	409	CR number already registered	رقم السجل التجاري مسجل بالفعل	Commercial registration number already in use by another company, on registration or on PATCH /admin/companies/:id
COMPANY_CREATE_FAILED	502	Failed to register company	فشل تسجيل الشركة	Company registration failed
COMPANY_INVALID_TRANSITION	409	Cannot {action} a {status} company	إجراء غير صالح لحالة الشركة الحالية	The status action (approve, reject, suspend, reactivate, archive, unarchive) is not valid for the company's current status
COMPANY_ARCHIVED	409	An archived company is read-only	لا يمكن تعديل شركة مؤرشفة	An internal-admin write on an archived company: editing it, inviting into it, starting review on, countering or rejecting its quote, confirming its contract, or recording its payment
COMPANY_LAST_ADMIN	409	The company's last active admin cannot be deactivated or removed	لا يمكن تعطيل أو حذف آخر مسؤول نشط في الشركة	PATCH /admin/users/:id with isActive: false, or DELETE /admin/users/:id, on the last active admin of a company
COMPANY_ADMIN_ROLE_LOCKED	409	A company admin's role cannot be changed	لا يمكن تغيير دور مسؤول الشركة	PATCH /admin/users/:id sends role for a b2b_admin target
COMPANY_NOT_APPROVED	403	Company is pending approval	الشركة في انتظار الموافقة	Portal route accessed by a member of a not-yet-approved company (also returned, with a different message, when a magic link is redeemed for — or POST /activations is attempted against — a company that isn't approved)
COMPANY_SUSPENDED	403	Company access is suspended	تم تعليق وصول الشركة	Portal route accessed by a member of a suspended company
COMPANY_REJECTED	403	Company registration was rejected	تم رفض تسجيل الشركة	Portal route accessed by a member of a rejected company
COMPANY_NOT_READY	409	This company isn't ready to send activation links yet — the contract and payment must be confirmed first	هذه الشركة غير جاهزة لإرسال روابط التفعيل بعد — يجب تأكيد العقد والدفع أولاً	Magic links minted before the contract + payment readiness gate is satisfied
COMPANY_BALANCE_EXCEEDED	409	This activation would exceed your company's available balance	سيؤدي هذا التفعيل إلى تجاوز الرصيد المتاح لشركتك	Flexible balance gate: drawn funds plus this seat's charge would pass the company's funded amount (also appears as a per-row code in the link-send failed array)

---

Quote Errors (400 / 404 / 409 / 502)

Returned by the B2B quote lifecycle endpoints. See B2B Portal and B2B Admin.

Code	Status	English Message	Arabic Message	Condition
QUOTE_NOT_FOUND	404	Quote not found	الطلب غير موجود	No quote with the given id (or, on the admin read, the quote is still a private draft)
QUOTE_INVALID_STATE	409	Varies with the action (e.g. "Quote has no items to confirm")	يختلف حسب الإجراء	The quote's status doesn't allow the requested action
QUOTE_CREATE_FAILED	502	Failed to create quote	فشل إنشاء الطلب	Quote draft creation failed
QUOTE_VERSION_SUPERSEDED	409	A newer version has superseded this one	استُبدلت هذه النسخة بنسخة أحدث	Action attempted on a quote version that a counter has since superseded
QUOTE_COUNTER_FAILED	502	Failed to create the countered version	فشل إنشاء النسخة المعدَّلة	Countering a quote failed
QUOTE_PACKAGE_NOT_FOUND	400	One or more packages do not exist or are not available for business orders	باقة واحدة أو أكثر غير موجودة أو غير متاحة لطلبات الأعمال	A quote line references a package id that doesn't exist or is not B2B-orderable (inactive, or no B2B price — the same surface the B2B catalog exposes). The offending ids are in error.details.packageIds

---

Contract Errors (400 / 404 / 409 / 502)

Returned by the B2B contract confirmation and payment endpoints. See B2B Portal and B2B Admin.

Code	Status	English Message	Arabic Message	Condition
CONTRACT_NOT_FOUND	404	Contract not found	العقد غير موجود	No contract with the given id
CONTRACT_ALREADY_EXISTS	409	This company already has an active contract	يوجد لدى هذه الشركة عقد نشط بالفعل	Confirming a quote for a company that already has an active contract
CONTRACT_ITEM_NOT_FOUND	404	Contract line not found on this company's active contract	بند العقد غير موجود ضمن العقد النشط لهذه الشركة	A roster package assignment references a contract line that doesn't belong to the company's active contract
CONTRACT_PACKAGE_PRICE_MISSING	400	One or more quoted packages have no B2B price set — cannot confirm this contract	باقة واحدة أو أكثر في طلب تحديد الباقات لا تملك سعر أعمال محدد — لا يمكن تأكيد هذا العقد	Confirming a quote where a quoted package has no priceSarB2b
CONTRACT_CREATE_FAILED	502	Failed to create contract	فشل إنشاء العقد	Contract creation failed
CONTRACT_PAYMENT_MODE_INVALID	409	Payments cannot be recorded for this contract	لا يمكن تسجيل الدفعات لهذا العقد	Recording a payment on a contract whose payment mode is neither prepaid nor flexible (legacy/invalid data — every contract is one or the other today)
CONTRACT_PAYMENT_BELOW_TOTAL	409	Payment amount is below the contract total	قيمة الدفعة أقل من إجمالي العقد	Recorded payment amount is less than the contract's totalSar
CONTRACT_PAYMENT_IDEMPOTENCY_CONFLICT	409	This idempotency key was already used for a different payment	مفتاح العملية مستخدم بالفعل لدفعة مختلفة	The same idempotencyKey was replayed with a different method or amount — replaying it with identical values returns the original record instead
CONTRACT_PAYMENT_DOCUMENT_INVALID_MIME	400	Unsupported document type	نوع المستند غير مدعوم	The uploaded payment document's MIME type isn't accepted
CONTRACT_PAYMENT_DOCUMENT_TOO_LARGE	400	Document must be 5MB or less	يجب ألا يتجاوز حجم المستند 5 ميغابايت	The uploaded payment document exceeds the 5MB size cap
CONTRACT_PAYMENT_RECORD_FAILED	502	Failed to record payment	فشل تسجيل الدفعة	Recording the payment failed
CONTRACT_PAYMENT_DOCUMENT_NOT_FOUND	404	Payment document not found	مستند الدفع غير موجود	The payment record has no supporting document to download

---

Roster Errors (404 / 409)

The B2B CSV roster staging endpoint returns no error envelope of its own. Row-level problems — invalid phone or email, a duplicate contact, or a contact a concurrent upload claimed first — come back as data in the rejected array of a 200 response. The same holds for the batch link routes, whose per-entry skips and failures are data too.

The two single-entry roster-control routes are the exception. PATCH /b2b/roster/:rosterId and DELETE /b2b/roster/:rosterId write one row, so they have no partial-accept response to carry a reason and throw instead. See B2B Portal.

Code	Status	English Message	Arabic Message	Condition
ROSTER_ENTRY_NOT_FOUND	404	Roster entry not found	صف القائمة غير موجود	No roster entry with the given id on the caller's own company roster (also appears as a per-entry skip code on the batch link routes)
ROSTER_LINK_OPEN	409	This person has an open invitation — revoke it first	لدى هذا الشخص دعوة مفتوحة — يجب إلغاؤها أولاً	A live, unexpired issued/sent/exported link still holds this seat, so the assignment cannot change and the person cannot be removed. Cleared with POST /b2b/roster/links/revoke.
ROSTER_SEAT_CONSUMED	409	This person already used their invitation — their seat is permanently theirs	استخدم هذا الشخص دعوته بالفعل — أصبح مقعده دائمًا	The beneficiary redeemed a link at some point. Redemption is permanent, even once that link is past its own expiry. The removal route also returns this code, with the message "This person already has activation history — their record cannot be removed", when the underlying account is no longer a bare staged end user.

---

Magic Link Errors (401 / 409)

Returned by POST /auth/magic-link on redemption. See Authentication.

Code	Status	English Message	Arabic Message	Condition
MAGIC_LINK_INVALID	401	This link is not valid	هذا الرابط غير صالح	Token doesn't match any issued magic link
MAGIC_LINK_ALREADY_USED	401	This link has already been used	تم استخدام هذا الرابط بالفعل	The link's status is already used (or it lost the race to consume it)
MAGIC_LINK_REVOKED	401	This link has been revoked	تم إلغاء هذا الرابط	The link was revoked before redemption
MAGIC_LINK_EXPIRED	401	This link has expired	انتهت صلاحية هذا الرابط	The link's 24h TTL has passed
MAGIC_LINK_USER_ALREADY_ACTIVE	409	This account already has an active SIM	يوجد لدى هذا الحساب شريحة مفعّلة بالفعل	Redemption succeeded but the user's latest activation is already activated. The link send/export routes pre-empt this at mint time with the per-entry skip LINK_USER_ALREADY_ACTIVE (same predicate), so a company-minted link should no longer reach this state

COMPANY_NOT_APPROVED (403) is also returned here — see Company Errors.

---

Document Errors (404 / 500)

Returned by GET /documents/:type/:entityId.pdf. See Documents.

Code	Status	English Message	Arabic Message	Condition
DOCUMENT_TYPE_NOT_FOUND	404	Document type not found	نوع المستند غير موجود	:type isn't a registered document type
DOCUMENT_NOT_FOUND	404	Document not found	المستند غير موجود	:entityId isn't a valid UUID, or no matching entity exists
DOCUMENT_RENDER_FAILED	500	Failed to render document	فشل إنشاء المستند	PDF rendering threw after the access policy and entity lookup both passed

---

Support and Officer Errors (403 / 404 / 409 / 422 / 503)

These codes are returned by /tickets, /admin/support, and /admin/officer. See Support Tickets and Activation Officer for route scope and state rules.

Code	Status	Meaning
TICKET_NOT_FOUND	404	Ticket is missing or outside the caller's ownership/assignment scope
TICKET_CLOSED	409	Closed ticket cannot receive comments or change status
TICKET_LINK_INVALID	422	Linked activation/store order is invalid or outside customer scope
TICKET_ASSIGNEE_INVALID	422	Assignee is not an active activation officer
TICKET_ACTION_NOT_ALLOWED	409	Ticket type, status, assignment, or transition refuses the action
REFUND_ORDER_NOT_PAID	422	Refund link is not on a paid order
REFUND_NOT_DECIDABLE	409	Activation approval requires failed or cancelled
REFUND_ALREADY_DECIDED	409	Refund decision already exists
REFUND_SELF_DECISION	403	Request opener cannot decide their own request
REFUND_DECIDER_CANNOT_OPEN	403	Caller holds the refund decider role, which never opens a refund request
REFUND_STORE_APPROVAL_DEFERRED	409	Store-linked approval is not enabled yet
OFFICER_CLAIM_TAKEN	409	Another officer claimed the row or it no longer needs attention
OFFICER_CLAIM_NOT_HELD	409	Caller does not hold the row claim
OFFICER_ACTION_NOT_ALLOWED	409	Officer action is invalid for the current state or scope
OFFICER_JOB_IN_FLIGHT	409	Completion job is still live
OFFICER_COMPANY_READ_ONLY	409	Company activation is visible but immutable in the officer console, and cannot get a refund request from any staff route
OFFICER_LOOKUP_FAILED	502	The officer console's direct operator lookup call failed or timed out
IDENTITY_START_UNAVAILABLE	503	Identity-start lease could not be acquired safely

Activation Errors (409 / 422)

Code	Status	English Message	Arabic Message	Condition
ACTIVATION_FAILED	422	Activation failed	فشل التفعيل	General activation failure
ACTIVATION_ICCID_INVALID	422	ICCID validation failed	فشل التحقق من رقم ICCID	Operator rejected ICCID
ACTIVATION_ESIM_DISABLED	422	eSIM activation is disabled	تفعيل eSIM غير مفعّل حاليًا	FEATURE_ESIM is off for an eSIM request, or a corporate B2B user attempted eSIM activation before that lane is enabled
ACTIVATION_CODE_INVALID	422	Invalid eSIM activation code	رمز تفعيل eSIM غير صالح	eSIM activation create reached the operator validation path and the LPA activation code was rejected
ACTIVATION_ESIM_UNSUPPORTED_OPERATOR	422	This operator does not support eSIM activation	هذا المشغل لا يدعم تفعيل eSIM	simType: esim was requested for an operator plugin that did not explicitly declare supportsEsim: true
ACTIVATION_PACKAGE_NOT_ON_CONTRACT	409	This package is not on your company's contract	هذه الباقة غير مدرجة في عقد شركتك	B2B activation: no roster entry, no assigned contract line, the requested package doesn't match the assigned line, or the contract is not active
ACTIVATION_LINK_NOT_REDEEMED	409	Open your company invite link before activating	يجب فتح رابط دعوة شركتك قبل التفعيل	B2B activation: the roster entry has no redeemed invite link — OTP login alone cannot activate a staged seat
ACTIVATION_SEAT_ALREADY_USED	409	This account already has an active or pending SIM	يوجد لدى هذا الحساب شريحة نشطة أو قيد التفعيل بالفعل	B2B activation: the seat already has a pending/in-progress/activated SIM (failed/cancelled allow retry)
IDENTITY_ERROR	422	Identity verification failed	فشل التحقق من الهوية	Identity verification initiation/retrieval failure
ACTIVATION_SERIAL_IN_USE	409	This SIM serial is already in use	رقم الشريحة مستخدم بالفعل	Customer activation creation found another paid activation already holding the ICCID

serial_in_use and officer_verified_failed are durable activation errorCode values, not HTTP envelope codes. serial_in_use is written when completion's first-claim check finds another physical activation already holding the serial. officer_verified_failed is written when an officer records evidence that the operator confirmed the line was not activated. The latter uses a fixed customer-facing reason and keeps typed evidence in audit data.

---

Identity Type and Number Errors (400 / 409)

Returned by the customer identity check (POST /activations/:id/verify-identity) and PUT /profile. See Activations and Profile.

Code	Status	English Message	Arabic Message	Condition
ID_NUMBER_INVALID	400	The identity number is not valid for this identity type	رقم الهوية غير صالح لنوع الهوية هذا	The number does not fit the identity type's format, or fails the check digit
ID_NUMBER_TYPE_MISMATCH	400	This identity number belongs to the other identity type. A national ID starts with 1 and an iqama with 2	رقم الهوية هذا يخص نوع الهوية الآخر. تبدأ الهوية الوطنية بالرقم 1 والإقامة بالرقم 2	A well-formed citizen number was checked as resident, or the reverse
IDENTITY_TYPE_LOCKED	409	The identity type cannot be changed while an identity check is waiting or after one has completed	لا يمكن تغيير نوع الهوية أثناء انتظار التحقق من الهوية أو بعد اكتماله	An identity type change was requested while an identity check for the customer is waiting, or after one has completed
IDENTITY_TYPE_COMPANY_MANAGED	409	A company employee's identity type comes from the company's roster	نوع هوية موظف الشركة يأتي من قائمة موظفي الشركة	An identity type change was requested for a company employee

Sending the identity type already on the record is never refused, locked or not. A citizen number is 10 digits starting 1, a resident number is 10 digits starting 2, and both must pass the check digit: the digits in places 1, 3, 5, 7 and 9 are doubled, a doubled value of 10 or more counts as the sum of its digits, and the total of all ten digits must be a multiple of 10. A visitor number keeps the looser 5 to 20 character rule.

---

eSIM Store Errors (400 / 404 / 409 / 422 / 503)

Returned by the public eSIM store, store-order, admin catalog, admin order recovery, FX settings, and manual sync endpoints. See eSIM Store.

Code	Status	English Message	Arabic Message	Condition
STORE_DISABLED	422	eSIM store is disabled	متجر eSIM غير مفعّل حاليًا	FEATURE_ESIM_STORE is off — gates browse (GET /store/destinations, GET /store/products, GET /store/products/:id) and store writes (POST /store/orders, POST /store/device-acks); GET /store/status stays public, and owned-order reads and the QR endpoint stay available so delivered codes are never locked out
STORE_PRODUCT_NOT_FOUND	404	Store product not found	منتج المتجر غير موجود	Product is missing, or public detail hides it because it is inactive
STORE_PRODUCT_INACTIVE	422	Store product is inactive	منتج المتجر غير متاح حاليًا	Buy request targets an inactive product
STORE_CURRENCY_UNSUPPORTED	400	Unsupported store currency	عملة المتجر غير مدعومة	Currency value is outside the supported USD / SAR / AED / EUR / GBP / EGP set, or a supported currency's FX rate has not been fetched yet (details.currency + details.detail). On list and buy routes, unsupported currencies are rejected as standard validation errors; on the detail route, the explicit currency param fires this code
STORE_KYC_REQUIRED	422	This eSIM requires KYC and cannot be purchased yet	تتطلب هذه الشريحة تحققًا من الهوية ولا يمكن شراؤها حاليًا	Buy request targets a KYC provider SKU whose provider does not support the async verification flow (or is not registered). With a supporting provider the purchase proceeds and issuance answers with a verification URL instead
STORE_ORDER_NOT_FOUND	404	Store order not found	طلب المتجر غير موجود	Store order is missing, foreign to the caller, or not issued yet for QR delivery; also returned by the admin order detail and requeue routes for unknown ids
STORE_SYNC_UNAVAILABLE	503	eSIM store sync is temporarily unavailable	مزامنة متجر eSIM غير متاحة مؤقتًا	Manual admin catalog sync could not be enqueued because Redis/queueing is unavailable
STORE_ORDER_NOT_REQUEUEABLE	409	Store order is not in a requeueable state	طلب المتجر ليس في حالة تسمح بإعادة الإدراج	Admin requeue targeted an order that is not paid-without-an-issued-profile (already issued, completed, cancelled, or still pending payment)
STORE_REQUEUE_UNAVAILABLE	503	Store fulfillment requeue is temporarily unavailable	إعادة إدراج تلبية طلب المتجر غير متاحة مؤقتًا	Admin requeue could not enqueue a store fulfillment job because Redis/queueing is unavailable
STORE_CHARGE_BELOW_MINIMUM	422	Charge amount is below the minimum allowed by payment processors	مبلغ الدفع أقل من الحد الأدنى المسموح به لمعالجات الدفع	The calculated store order charge amount is below the mandatory minimum threshold
STORE_PROVIDER_PAYMENT_EXTERNAL	422	External provider checkout is not supported yet	الدفع عبر مزوّد الخدمة غير مدعوم بعد	The store order's provider has payment_mode = 'external'. Fail-closed — order creation and card/Apple Pay payment initiation both block before any insert or PSP call. Missing linkage or unrecognised mode values throw the same code.
STORE_PRICE_CHANGED	409	Store product price has changed; re-fetch the product and retry with the current price	تغيّر سعر منتج المتجر؛ يرجى إعادة جلب المنتج والمحاولة بالسعر الحالي	Optional expectedPrice guard on POST /store/orders: the request carried expectedPrice and it was not strictly equal to the freshly computed presentment price.amount; details.currentPrice: { amount, currency } carries the current price so the client can re-render without a refetch
STORE_PROVIDER_NOT_FOUND	404	Store provider not found	مزوّد المتجر غير موجود	Admin provider toggle (PATCH /admin/store/providers/:id) targeted an id with no eSIM operator row — telecom operators are invisible to this route by design
STORE_PROVIDER_UNAVAILABLE	422	Store provider is temporarily unavailable	مزوّد المتجر غير متاح مؤقتًا	Checkout circuit breaker on POST /store/orders: the product's provider plugin is not registered in this process, its latest health reading is unhealthy, or the health check itself failed (fail closed)

---

Payment Errors (402 / 404)

Code	Status	English Message	Arabic Message	Condition
PAYMENT_INTENT_FAILED	402	Payment intent creation failed	فشل إنشاء نية الدفع	Payment checkout creation error
PAYMENT_METHOD_NOT_SUPPORTED_FOR_ORDER	422	This payment method is not available for eSIM store orders	طريقة الدفع هذه غير متاحة لطلبات متجر الشرائح الإلكترونية	mada or STC Pay attempted on an eSIM store order; cards and Apple Pay are the only supported store rails
PAYMENT_APPLE_PAY_FAILED	402	Apple Pay payment failed	فشل دفع Apple Pay	Apple Pay confirmation failed
PAYMENT_STCPAY_FAILED	402	STC Pay initiation failed	فشل بدء عملية STC Pay	STC Pay initiation error
PAYMENT_RECEIPT_FAILED	402	Receipt retrieval failed	فشل استرجاع الإيصال	Receipt generation error
PAYMENT_ORDER_INVALID_STATUS	402	Order is not in pending_payment status	الطلب ليس في حالة انتظار الدفع	The order is not in pending_payment when a payment create call is attempted
PAYMENT_IDEMPOTENCY_CONFLICT	402	Idempotency conflict	تعارض مفتاح الوحدة	Same idempotency key with different parameters
PAYMENT_MISMATCH_RECORD_FAILED	500	Failed to record the payment mismatch	فشل تسجيل عدم تطابق الدفعة	Writing the reconciliation record and the failed-payment transition both failed on a mismatched webhook. Returned to the provider so it redelivers the event
ORDER_NOT_FOUND	404	Order not found	لم يتم العثور على الطلب	The payment request referenced an order that does not exist or is not owned by the caller

Idempotency conflict response:

{
  "error": {
    "code": "PAYMENT_IDEMPOTENCY_CONFLICT",
    "message": "A payment with this idempotency key already exists with different parameters",
    "details": {
      "existingPaymentId": "d5e6f7a8-b9c0-1234-defa-567890123456"
    }
  }
}

---

Operator Errors (502 / 504)

Code	Status	English Message	Arabic Message	Condition
OPERATOR_UNAVAILABLE	502	Operator API unavailable	خدمات المشغل غير متاحة	Operator API returned error
OPERATOR_TIMEOUT	504	Operator API timed out	انتهت مهلة خدمات المشغل	Operator API did not respond in time

---

Server Errors (5xx)

Code	Status	English Message	Condition
INTERNAL_ERROR	500	An unexpected error occurred	Unhandled server error
NOT_IMPLEMENTED	501	This endpoint is not yet implemented	Endpoint stub (not yet built)

---

Rate Limiting (429)

When the rate limit (100 requests / 15 minutes / IP) is exceeded, or the separate auth-surface limit (AUTH_RATE_LIMIT_*, keyed per IP on the anonymous auth routes and per signed-in user on /auth/change-phone and /auth/verify-change-phone):

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests, please try again later"
  }
}

Response headers include:

Header	Description
X-RateLimit-Limit	Maximum requests per window
X-RateLimit-Remaining	Requests remaining in current window
X-RateLimit-Reset	Window reset timestamp (Unix epoch)

---

Payment gateway and webhook errors

Moyasar and Paymob errors. All messages are bilingual.

Code	HTTP	Meaning
PAYMENT_GATEWAY_DISABLED	503	New payments disabled
MOYASAR_NOT_CONFIGURED	503	Selected profile missing
MOYASAR_CREDENTIALS_REQUIRED	422	First setup requires all keys
MOYASAR_CREDENTIALS_UNREADABLE	503	Stored credentials cannot be decrypted
PAYMENT_RETURN_NOT_CONFIGURED	503	Moyasar only: the API could not tell its public address; set a custom HTTPS return URL or PUBLIC_API_URL
MOYASAR_UNAVAILABLE	503	Provider transport failure; retry
MOYASAR_REQUEST_FAILED	404/502	Provider lookup or credential failure
MOYASAR_RESPONSE_INVALID	502	Invalid provider response
MOYASAR_WEBHOOK_UNAUTHORIZED	401	Webhook secret mismatch
PAYMOB_NOT_CONFIGURED	503	Selected Paymob profile missing
PAYMOB_CREDENTIALS_REQUIRED	422	First setup requires public key, secret key and card integration ID, plus the API key for production
PAYMOB_CREDENTIAL_VERSION_UNKNOWN	503	Saved Paymob credential generation is unavailable
PAYMOB_CREDENTIALS_UNREADABLE	503	Stored credentials cannot be decrypted
PAYMOB_UNAVAILABLE	503	Provider transport failure; retry
PAYMOB_REQUEST_FAILED	404/502	Provider lookup or credential failure
PAYMOB_RESPONSE_INVALID	502	Invalid provider response
PAYMOB_WEBHOOK_INVALID	400	Malformed hmac or callback body
PAYMOB_WEBHOOK_UNAUTHORIZED	401	HMAC signature missing or mismatched while an HMAC secret is saved
PAYMOB_WEBHOOK_QUEUE_UNAVAILABLE	503	Queue handoff failed; Retry-After: 1
PAYMENT_CURRENCY_UNSUPPORTED	422	Gateway does not charge this currency (Paymob: SAR only)
PAYMENT_METHOD_UNAVAILABLE	422	Requested method has no saved Paymob integration
PAYMENT_ENVIRONMENT_MISMATCH	409	Event mode differs from saved payment
PAYMENT_ALREADY_STARTED	409	error.details contains owned paymentId and original idempotencyKey to resume
PAYMENT_ORDER_CHANGED	409	Refresh changed order total
PAYMENT_AMOUNT_UNSUPPORTED	422	Minimum charge is 100 minor units (1.00)
PAYMENT_ID_INVALID	400	Payment ID is not UUID
PAYMENT_NOT_FOUND	404	Owned gateway payment not found

SIM Limits (CITC)

Per CITC regulations, users are limited by identity type:

Identity Type	Max SIMs	identityType Value
Citizen	10	citizen
Resident	2	resident
Visitor	1	visitor