Use this section to diagnose and resolve common issues when working with the API.
This helps you interpret error responses, check request details, verify authentication and permissions, and identify problems with parameters, headers, payloads, rate limits, or service availability.
Before you contact support, review the relevant status code, response message, and request configuration to help isolate the cause of the issue and determine the next step.
Model Status & Divergence Issues
Archived, locked, offline, or deployed models
If a model is archived, locked, offline, busy, or in a deployed mode state that prevents the requested change, API calls can fail or return incomplete results. Check the model state in Anaplan and confirm that the requested operation is allowed for that model state.
Synchronization and task failure
Model synchronization failed
The target workspace may not have enough remaining storage memory to accept the incoming model update. The API response will reflect the current size, the size after sync, and the workspace limit.
Resolution:
- Increase the workspace size limit in the Administration Console (requires Tenant Admin).
- Navigate to the target workspace and delete unused, draft, or archived models to free up physical space.
- Clean up list items or transitional transactional data in the target model.
Task status query returns HTTP 500 "Internal Server Error"
A process task containing non-import/export actions (such as sub-actions or custom scripts) was triggered, and an action within it failed internally. The API fails to return the exact task state.
- Resolution:
- Immediate Workaround: Run the process manually inside the Anaplan model UX to isolate and identify the exact action that is failing.
- Integration Best Practice: Isolate import/export tasks into dedicated API sequences instead of packing them into single large process sequences containing unsupported sub-actions.
ALM HTTP error messaging
Aside from standard HTTP errors, the ALM API can have different root causes and resolutions:
| HTTP status | API error message context | Recommended action |
| 400 | Check if the content is compatible with JSON format. | Re-verify that payload conforms to JSON formatting standards. |
| 400 | Check if the values are compatible with JSON. | Eliminate formatting syntax anomalies (e.g. smart-quotes). |
| 400 | An unterminated string was identified. Ensure the string is terminated. | Check for missing double quotes inside body parameters. |
| 400 | An unterminated JSON object was found. Ensure the object is terminated. | Ensure all opening brackets { contain closing brackets }. |
| 400 | Identified an unrecognized ‘<field_name>’. Amend the content so it only contains applicable fields. | Remove unsupported JSON body properties. |
| 400 | The data provided is not in the expected format. Change the data format. | Validate properties align with API types (e.g., matching lists vs arrays). |
| 400 | Found a value with an unexpected string format when <expected_type> was expected. | Ensure variables match types (e.g., supplying strings where integers are required). |
| 400 | The request body is null. To continue, change the format to a non-empty state. | Provide a valid, non-empty JSON body when calling POST/PUT actions. |
| 400 | Cannot change status when model is in Locked or Archived mode | Change the model mode status so it’s unlocked and unarchived. |
| 400 | Missing 'sourceModelId' request parameter. | Specify the sourceModelId. This is mandatory. |
| 400 | Error parsing request body as JSON [...] | Check that you’ve only included the properties listed in the request body guidance. |
| 400 | Expected mandatory fields 'sourceRevisionId', 'sourceModelId' and 'targetRevisionId' | Add the mandatory fields for the call to be successful. |
| 400 | The title of your revision tag must be 60 characters or fewer. | Check if name exceeds 60 characters. |
| 400 | Revision tag descriptions must be 250 characters or fewer. | Check if description exceeds 250 characters. |
| 400 | Date query parameter must be of the format 'YYYY-MM-DD' | Change date format to YYYY-MM-DD. |
| 400 | 'appliedAfter' must be an earlier date than 'appliedBefore' | Ensure appliedAfter is earlier than appliedBefore. |
| 403 | Forbidden | Validate administrative privileges and active auth token status. |
| 404 | Not Found | Verify the request path URL variables and target Model/Workspace IDs. |
| 422 | Model is Archived | Model is locked and cannot receive operations. Unarchive the model. |