Altera shows a code such as ABC001 with each error or warning. This article explains the codes for this area of the app and how to resolve them. For codes from other areas, see Error and warning codes.
Access Codes
Error codes about signing in to the app, store access tokens, API keys, data and connection permissions, and Shopify access scopes.
ACC001 - Invalid Session Token
The session token Shopify sent when opening the app could not be verified. When a token has expired, for example after the app has been open in a browser tab for a long time, Altera requests a new one from Shopify automatically. You see this error only when the new token could not be verified either, or when the page was loaded outside of the Shopify admin.
Reload the page from the Shopify admin. If it keeps happening, clear your browser cache or try a different browser, then contact support.
Previous code: AUTH001.
ACC002 - Session Token for Another Store
The session token Shopify sent belongs to a different store than the one in the page address. Altera only opens the store that the token names.
Open the app again from the Shopify admin of the store you want to use. If it keeps happening, contact support.
Previous code: AUTH002.
ACC003 - Refresh Token Expired
The token used to keep Altera's access to the store alive has expired (Shopify refresh tokens last 90 days). This usually means the store has been inactive, paused, or frozen for an extended period.
To resolve this, open the Altera app from your Shopify admin. This re-authenticates the store automatically and background jobs will work again.
Previous code: TOKN001.
ACC004 - Token Refresh Rejected
Shopify rejected Altera's attempt to refresh its access token for the store. This can happen if the store is paused or frozen, or if the token state is out of sync.
To resolve this, open the Altera app from your Shopify admin to re-authenticate the store. If the store is paused or frozen, the store owner needs to reactivate it first.
Previous code: TOKN002.
ACC005 - Token Refresh Timeout
Another process was refreshing the store's access token and did not finish in time. This is a temporary condition.
Retry the operation. If it keeps happening, contact support.
Previous code: TOKN003.
ACC006 - Token Exchange Incomplete
Shopify accepted Altera's token exchange for the store but did not return an expiring access token and refresh token pair, so Altera could not store the credentials.
Open the Altera app from your Shopify admin to re-authenticate the store. If it keeps happening, contact support.
Previous code: TOKN004.
ACC007 - Access Token Not Set
The Shopify API client was started without an access token. This is an internal error.
Run the job again. If it keeps happening, contact support with your job ID.
Previous code: GQL005.
ACC008 - No Access Token for Store
Altera has no access token stored for this store, so it cannot call the Shopify API. This happens when the app has been uninstalled, or the store's credentials were removed.
Open the Altera app from your Shopify admin to re-authenticate the store. If the app was uninstalled, reinstall it from the Shopify App Store. Background jobs on the store cannot run until this is resolved.
Previous code: GQL006.
ACC009 - API Key Permission Denied
This error occurs when the API key being used does not have the necessary permissions to perform the requested operation. Each API key can be configured with specific permissions that control which types of jobs (imports or exports) and which object types (products, orders, customers, etc.) it can access.
Common reasons for this error include:
The API key is restricted to certain object types and you're trying to access a different type
The API key only has export permissions and you're trying to import data
The API key only has import permissions and you're trying to export data
How to fix this:
Review your API key permissions in the Altera settings
Create a new API key with the appropriate permissions for your use case
Previous code: API001.
ACC010 - Store Data Permission Denied
This error occurs when the store's data permissions do not allow the requested import or export operation. The store owner can configure which data types are allowed for import and export in Settings > Data permissions.
How to fix this:
Ask the store owner to review the data permissions in Settings
The store owner can enable the required data type for import or export
Previous code: PERM001.
ACC011 - Import Type Not Permitted
This error appears during file analysis when a sheet in your spreadsheet is mapped to a data type that the store's data permissions do not allow for import. The sheet will be skipped during import.
How to fix this:
Ask the store owner to enable the required data type for import in Settings > Data permissions
Alternatively, change the sheet type mapping to a permitted data type
Previous code: PERM002.
ACC012 - Owner Permission Required
This error occurs when a non-owner user attempts to change the store's data permissions. Only the store owner can modify data permission settings.
How to fix this:
Ask the store owner to make the desired changes to data permissions
Previous code: PERM003.
ACC013 - Connection Permission Denied
This error occurs when an AI tool connected through Altera's MCP server tries to perform an operation the connection was not granted access to. When the connection was authorized, it was limited to specific resources (for example, read-only access to products). Read access corresponds to exports; write access corresponds to imports.
Connection permissions cannot be edited after the fact. To change them, the connection must be disconnected and reconnected, granting the new set of permissions on the authorization screen.
How to fix this:
Disconnect the AI tool and reconnect it, granting the required read or write access on the consent screen.
Manage existing connections in Settings > MCP connections.
Previous code: MCPO001.
ACC014 - Missing Shopify Scope
This error occurs when a feature requires a Shopify access scope that the merchant has not granted. Some Altera features are gated behind optional Shopify scopes that are only requested when needed. For example, exporting or importing inventory transfers requires the read_inventory_transfers and write_inventory_transfers scopes.
Uninstalling Altera removes these optional scopes. After a reinstall, the app asks for them again the next time you create an export or import that needs them. Jobs started another way, such as Run again, a schedule, the CLI, or an AI assistant, fail with this code until the scopes are granted.
How to fix this:
Create a new export or import for the affected data type in Altera. The app prompts you to authorize the scopes.
Or grant the scopes from Settings > Permissions.
Only the store owner can grant new scopes. If you are a staff member, ask the store owner to authorize.
Previous code: SCPE001.
ACC015 - No Impersonation Shop Set
A request came in through the support impersonation domain, but no store is selected for the current user, or the selection is older than one hour and has expired. Select a store to impersonate and try again.
Previous code: IPN001.
ACC016 - Invalid Data Permissions Value
The data_permissions value sent to the Altera API is not in the expected format. It must be an object that maps each data type to its permissions, or empty to remove all restrictions.
This error comes from a request to the Altera API, not from the app. Correct the request body and send it again.
Previous code: PERM004.
Shopify API Codes
These codes occur when interacting with the Shopify API.
SAPI002 - Shop is Closed
Your import or export failed because the Shopify store is currently closed or paused, and API requests cannot be made to the store. This can happen when:
The store owner has paused their Shopify subscription
The store is in a frozen state due to billing issues
The store has been temporarily closed by the owner
To resolve this, the store owner needs to reactivate their Shopify subscription or unpause their store in the Shopify admin.
SAPI003 - Shop Uninstalled App
The Shopify store has uninstalled the Altera app, so API requests can no longer be made on behalf of this store.
If you believe this is an error, you can reinstall the app from the Shopify App Store.
SAPI004 - Shop is Unavailable
Your import or export failed because the Shopify store is not available and API requests cannot be made to the store. This can occur when:
The store has been permanently closed or deleted
There are temporary connectivity issues with Shopify
Shopify has flagged the store as fraudulent and blocked API access
SAPI006 - Daily Variant Creation Limit Reached
Shopify imposes a daily limit on the number of product variants that can be created through the API. This error occurs when you've reached that limit for the current day.
When you encounter this error:
Wait 24 hours after hitting the limit before continuing to create variants
Consider breaking your import into smaller batches spread across multiple days
Focus on updating existing variants instead of creating new ones if possible
Contact Shopify Support if you need information about your specific daily limits
This is a Shopify platform limitation and cannot be bypassed through the application.
SAPI008 - Shopify API Error
An error was returned from the Shopify API that was not related to internal server issues or product modification conflicts. This could be due to various reasons such as invalid data, API limitations, or other Shopify-specific constraints. The exact error message from Shopify will be provided with this code to help diagnose the specific issue.
SAPI009 - Shopify Internal Server Error
This error indicates that Shopify's servers encountered an internal error while processing the API request. This is not caused by your data or configuration -- it is an issue on Shopify's end.
Altera automatically retries this error for most object types by reducing the page size and re-attempting the request. In most cases, the operation will succeed after one or more retries without any action needed from you.
If the error persists after automatic retries:
Wait a few minutes and try running the job again
If the issue continues, please contact us at [email protected] so we can investigate further
SAPI010 - API Rate Limit Exceeded
Altera allows you to run multiple jobs at the same time and has a built-in retry mechanism when Shopify's API rate limits are reached. However, if many intensive API jobs are running simultaneously, the retries may exceed the maximum allowed attempts, causing the job to fail.
To resolve this:
Reduce the number of jobs running at the same time
Wait a few minutes and retry the failed job
If you continue to experience this issue, please contact us at [email protected]. We can adjust the API call allocation per job on our end to help prevent this from happening.
SAPI011 - Page Fetch Failed After Retries
Shopify kept returning an error or timing out for one page of data, even after Altera reduced the page size to the minimum and retried several times. This usually happens when a few records have very large content, such as long descriptions or many metafields, or during a Shopify service disruption.
To resolve this:
Wait a few minutes and run the job again
Reduce the amount of data per record by exporting fewer columns, such as leaving out metafields
Check the Shopify status page if the problem continues
Contact support with your job ID if the job keeps failing on the same data
SAPI013 - Unable to Connect to Shopify API
Altera could not get a response from Shopify's API after retrying. This is a network or Shopify-side condition, not a problem with your file.
Wait a few minutes and run the job again. Check the Shopify status page if the problem continues.
SAPI014 - File Status Timeout
This error occurs when waiting for files to reach a terminal status (READY or FAILED) but the operation times out before all files complete processing. This can happen when:
Files are taking longer than expected to process on Shopify's end
There are issues with Shopify's file processing infrastructure
If you encounter this error, you can try:
Processing fewer files at once
Making sure that the remote server with the media is available and accessible
User Error Codes
These codes appear when Shopify rejects an operation due to validation issues or business rule violations.
USR001 - Shopify Validation Error
This error occurs when Shopify rejects the data you're trying to submit because it doesn't meet their requirements. Unlike technical API errors, these are usually related to the actual content of your data.
Common reasons for this error include:
Missing required fields (e.g., a product without a title)
Invalid data formats (e.g., incorrect date format)
Business rule violations (e.g., trying to set a price lower than allowed)
Duplicate data (e.g., attempting to create a product with an existing SKU)
Resource constraints (e.g., exceeding allowed inventory levels)
The error message accompanying this code will provide specific details about what went wrong, which should help you correct your data before trying again.
Plan Codes
Error codes related to activating or changing an Altera plan.
PLN001 - App Not Installed for Plan Activation
A plan could not be activated because the app is no longer installed on the store. Reinstall Altera from the Shopify App Store and choose the plan again.
PLN002 - App Not Installed for Charge Creation
A subscription charge could not be created because the app is no longer installed on the store. Reinstall Altera from the Shopify App Store and choose the plan again.
PLN003 - Discount Amount or Percentage Required
A discounted plan was requested but neither a discount amount nor a discount percentage was set. This is an internal configuration error. Contact support.
PLN004 - Discount Amount and Percentage Both Set
A discounted plan was requested with both a discount amount and a discount percentage. Only one can be applied. This is an internal configuration error. Contact support.
PLN005 - Shopify Refused to Create the Subscription
Shopify rejected the request to create the app subscription. The message includes the reason Shopify gave. Common causes are a store that is paused, frozen, or on a plan that does not allow app charges, or a store that has not finished the Shopify trial setup.
Check the store's status in the Shopify admin and try again. If the problem continues, contact support with the message text.