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.
Common HTTP errors
| HTTP status | Common meaning | What to check |
| 400 | Bad request | Request body, required parameters, date formats, unsupported values. |
| 401 | Unauthorized | Missing, expired, invalid, or incorrectly formatted authentication token. |
| 403 | Forbidden | User lacks permission for the model, object, or action. |
| 404 | Not found | Incorrect ID, unavailable object, missing access, wrong endpoint, or object not visible to the user. |
| 409 | Conflict | Model or object busy, conflicting action, or state mismatch. |
| 429 | Too many requests | Rate limit exceeded; retry with backoff. |
| 500 | Server error | Retry if transient; if persistent, capture request details and task output for support. |
Common task failures
Task failures usually appear in the task result rather than as HTTP request failures. Inspect:
- Task state.
- Current step.
- Failure counts.
- Nested action results for processes.
failureDumpAvailable.- Object IDs referenced in the task result.
Common causes include:
- Import source file not uploaded or not marked complete.
- Import mapping mismatch.
- Missing list members.
- Invalid dates, numbers, or text encoding.
- Model role does not have access to the import, export, module, list, or action.
- Selective Access or Dynamic Cell Access restrictions.
- Process contains an action the integration user cannot run.
Permissions issues
Confirm that the integration user can:
- Authenticate successfully.
- Access the workspace and model.
- See the required model objects.
- Run the required import, export, process, or delete action.
- Read or write the target modules, lists, views, and line items.
- Access source or output files.
Some endpoints require Workspace Administrator permission.
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.
Retry guidance
Use retries only for transient failures. Do not blindly retry validation, mapping, or permission errors.
Recommended approach:
- Retry
429,409, and transient5xxresponses with exponential backoff and jitter. - Use a reasonable maximum retry count.
- Avoid polling task endpoints too frequently.
- For task failures, inspect and fix the cause before retrying.
- Make upload and action workflows idempotent where possible, so a failed integration can resume safely.
