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 statusCommon meaningWhat to check
400Bad requestRequest body, required parameters, date formats, unsupported values.
401UnauthorizedMissing, expired, invalid, or incorrectly formatted authentication token.
403ForbiddenUser lacks permission for the model, object, or action.
404Not foundIncorrect ID, unavailable object, missing access, wrong endpoint, or object not visible to the user.
409ConflictModel or object busy, conflicting action, or state mismatch.
429Too many requestsRate limit exceeded; retry with backoff.
500Server errorRetry 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:

  1. Retry 429, 409, and transient 5xx responses with exponential backoff and jitter.
  2. Use a reasonable maximum retry count.
  3. Avoid polling task endpoints too frequently.
  4. For task failures, inspect and fix the cause before retrying.
  5. Make upload and action workflows idempotent where possible, so a failed integration can resume safely.