Error Codes

Every error response includes a code field that identifies the specific error. Use this reference to understand what went wrong and how to fix it.

Response Format

{
  "message": "Human-readable error description",
  "code": "error_code",
  "status": 401
}

The HTTP status code always matches the status field in the body.

Authentication Errors (4xx)

missing_token — 401

Message: "Access denied. Provide Bearer token or X-Client-Id + X-Client-Secret."

Cause: The request has no authentication credentials.

Resolution: Include either a Authorization: Bearer <token> header or client credentials (X-Client-Id, X-Client-Secret, X-Store-Id). See Authentication.

invalid_token — 401

Message: "Invalid or expired access token."

Cause: The Bearer token is expired, revoked, or malformed.

Resolution:

• OAuth tokens expire after 24 hours. Use the refresh token to obtain a new access token.
• Custom App tokens expire after 1 year. Regenerate from Settings > Apps > Manage.
• Verify the token starts with sx_at_ and was copied completely.

invalid_client — 401

Message: "Invalid client_id." or "Invalid client_secret."

Cause: The X-Client-Id or X-Client-Secret header value doesn't match any registered app.

Resolution:

• Verify both values were copied exactly from app creation (no extra whitespace).
• Client IDs start with sx_app_, secrets start with sx_secret_.
• If the secret was lost, rotate it from the Manage page (Custom Apps) or contact the platform admin (Platform Apps).

missing_store_id — 400

Message: "X-Store-Id header (or store_id param) is required with client credentials."

Cause: Using client credentials (X-Client-Id + X-Client-Secret) without specifying which store to access.

Resolution: Add the X-Store-Id header with the numeric store ID. This header is only required with client credentials, not with Bearer tokens (which encode the store internally).

not_installed — 401

Message: "App is not installed for this store."

Cause: The app exists but has no active installation for the specified store.

Resolution:

• Check that the X-Store-Id matches a store where your app is installed.
• If using a Custom App, verify it hasn't been deleted.
• If using a Platform App, the merchant may have uninstalled it.

missing_auth — 401

Message: "App authentication required."

Cause: The scope middleware detected that the request wasn't authenticated by appAuth.

Resolution: Ensure your request passes through the appAuth middleware by including valid credentials.

Authorization Errors

store_inactive — 403

Message: "Store is suspended or inactive."

Cause: The store associated with the credentials is frozen or suspended by the platform.

Resolution: Contact the store owner or SeloraX support. API access is blocked for frozen stores.

insufficient_scope — 403

Message: "Insufficient scope. Required: scope"

Cause: Your app doesn't have the OAuth scope required by the endpoint.

Resolution:

• Check the required scope in the endpoint documentation (e.g. read:orders for the Orders API).
• For Custom Apps, update scopes from Settings > Apps > Manage.
• For Platform Apps, update the requested_scopes in your app configuration. Merchants who already installed your app may need to re-authorize.

Extra field: The response includes required_scope with the specific scope name:

{
  "message": "Insufficient scope. Required: read:orders",
  "code": "insufficient_scope",
  "required_scope": "read:orders",
  "status": 403
}

Billing Errors

invalid_amount — 400

Cause: The charge amount is outside the allowed range (e.g. negative, zero, or exceeds the platform maximum).

Resolution: Check the billing endpoint documentation for valid amount ranges.

invalid_installation — 400

Cause: The app installation referenced in the billing request is inactive, uninstalled, or not found.

Resolution: Verify the app is currently installed for the target store.

charge_not_found — 404

Cause: The specified charge ID does not exist or doesn't belong to the authenticated app/store.

Resolution: Verify the charge ID and that it was created by your app for the target store.

insufficient_balance — 400

Cause: The store's wallet balance is too low to cover the requested debit.

Resolution: The merchant needs to top up their wallet balance before your app can debit from it.

Resource Errors

duplicate_name — 409

Cause: A custom app with the same name already exists for the store.

Resolution: Choose a unique name for the custom app.

Server Errors

auth_error — 500

Message: "Internal error during authentication."

Cause: An unexpected error occurred during the authentication process.

Resolution: This is a server-side issue. Retry the request. If it persists, contact SeloraX developer support.

HTTP Status Summary