6.3Controller APIs and interpreting REST responses

What burns the most time in controller-API automation is misreading the returned code and trying to fix the wrong thing. Rewriting the URL over and over when a 401 came back, or retrying instantly on a 429 and jamming things further—both stem from failing to read where the code says responsibility lies. Broadly, status codes signal a division of responsibility: 2xx = success, 4xx = the caller's (client's) problem, 5xx = the server's problem. Using the real controllers Catalyst Center and SD-WAN Manager, this section follows the full arc of obtaining an auth token -> making the call -> interpreting the response -> choosing the next action.

6.3.1The shape of a controller API call

• Catalyst Center (formerly DNA Center) is an on-prem controller governing the enterprise access network, exposing the Intent API. A call first obtains a token by sending credentials with Basic auth to POST /dna/system/api/v1/auth/token, then carries that token in the X-Auth-Token header to intent-based endpoints such as /dna/intent/api/v1/network-device. Tokens expire, and calls after expiry return 401.
• SD-WAN Manager (vManage) is the management controller for the WAN overlay, handling device inventory, templates, policies, and statistics over REST. After authenticating you call endpoints such as /dataservice/device, maintaining a session (and a CSRF token) for operations. On both controllers the pattern is the same: authentication is a separate request, and subsequent calls present credentials in a header.
• The HTTP method expresses the kind of operation: GET = read (safe, changes nothing) / POST = create (spawns a new resource or job) / PUT = replace (fields you omit may be cleared) / PATCH = partial update / DELETE = remove. On controllers a POST often does not complete immediately but returns a "task ID" for asynchronous processing, in which case you must GET the task-status endpoint to confirm completion.

6.3.2Where the status code places responsibility

• 2xx = success. 200 OK means the request succeeded with a body (payload) (typical of GET). 201 Created means a new resource was created (typical of POST, with the location given in a Location header or the body). 204 No Content means success with no body to return (typical of DELETE and some updates)—reading a 204 as failure and re-running it risks double execution.
• 4xx = the caller's problem, so retrying the identical request will not fix it. 400 Bad Request means the request's form or content is invalid (JSON syntax error, missing required field, type mismatch) -> fix the payload. 401 Unauthorized means not authenticated (no token presented, expired, or wrong credentials) -> re-obtain the token. 403 Forbidden means authentication succeeded but authorization is lacking -> review the account's role/permissions (re-fetching a token yields the same result).
• 404 Not Found means the specified resource (URL) does not exist -> check the endpoint path and resource ID spelling (unlike 401, this is not a credentials problem). 429 Too Many Requests means you hit the rate limit -> do not retry immediately; honor the Retry-After header if present and resend with exponential backoff (lowering concurrency or switching to a bulk fetch also helps).
• 5xx = the server's problem (500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable), and the request itself is likely correct. Rewriting the payload or token is therefore beside the point; the right move is retry with backoff plus checking the controller's logs and health. A 503 usually indicates transient overload or maintenance.

Suppose you operate a script that pulls the full device inventory from Catalyst Center and then fetches interface details per device. One morning the run log records three responses in sequence: the inventory call GET /dna/intent/api/v1/network-device returned 401 Unauthorized; a re-run of the same call returned 200 OK with a list of 500 devices; and partway through the per-device interface loop, 429 Too Many Requests began repeating. The common mistake here is seeing the 401, concluding "the account lacks permissions," and asking an administrator for a role upgrade. But 401 is an authentication failure (who you are cannot be verified), whereas 403 is what signals insufficient permission (authenticated but not allowed). The log shows the call succeeded with 200 on a mere re-run—so the credentials and role were fine and the correct reading is that the token had simply expired. The durable fix is not a role change but adding logic that tracks token lifetime and, on a 401, automatically re-fetches from /auth/token and retries exactly once. As for the 429, reading it as "the server broke" and retrying immediately and repeatedly is the worst move, since it trips the rate limit further and delays recovery. A 429 is the controller explicitly saying "you are calling too much," so honor the Retry-After header if present and otherwise space calls with exponential backoff (1s, 2s, 4s...). The more structural improvement is to revisit the design of querying 500 devices one at a time, using bulk endpoints or pagination to cut the number of calls. Had a 500 been returned instead, the diagnosis inverts: the request is correct but processing failed on the controller, so touching the payload or token is beside the point—back off and retry while checking controller health and logs. Likewise, if a POST registering a new device returns 202 or a body containing a task ID, it means the work is not finished, and you must not treat it as success until you GET the task-status endpoint and confirm completion. Conversely, when a DELETE returns 204 No Content, treating the empty body as failure and re-running it is dangerous—204 means success with nothing to return, and the deletion has in fact completed. In short, ENCOR asks not for the semantics of the code itself but for the choice of next move: "given this code, is what needs fixing the payload, the credentials, the permissions, the URL, or the call rate—or should nothing be changed and you simply wait?"

6.3.3Section summary

• Both Catalyst Center's Intent API and SD-WAN Manager (vManage) share the pattern of authenticating in a separate request and presenting the token/session in a header
• Split codes by where responsibility lies—2xx = success (including 204), 4xx = the caller (400 payload, 401 token, 403 permissions, 404 URL, 429 rate), 5xx = the server
• What is asked is not semantics but the next action: re-obtain the token on 401, review permissions on 403, honor Retry-After with exponential backoff on 429, and retry unchanged with backoff on 5xx