6.5 Interpret REST API response codes and results in payload using Cisco Catalyst Center and RESTCONF

A REST API response has two parts you must always read:

1. the status code;
2. the payload.

The status code tells you the general result. The payload gives the details. In network automation, both matter.

A 200 can still return the wrong data if your filter was wrong. A 204 can be a success even though there is no body. A 401 points to authentication. A 404 may mean the resource path or ID is wrong. A 500 usually means the server or controller had a problem.

REST basics

REST uses HTTP methods to act on resources.

The resource is usually represented by a URL.

https://controller.example.com/dna/intent/api/v1/network-device

or a RESTCONF path:

https://router.example.com/restconf/data/ietf-interfaces:interfaces

Client GET + Authorization
Client PATCH malformed JSON
Client POST job request
API response
API error
API job accepted

Read the status code first, then the JSON error or detail field. A 401 means fix auth. A 404 often means the URL or object ID is wrong.

Status code families

You do not need every HTTP code. Know the families and the common codes.

2xx: success

204 is a common trap. No body does not mean failure.

3xx: redirection

In API work, unexpected redirects can mean you used HTTP instead of HTTPS or hit a login page rather than the API.

4xx: client-side problem

5xx: server-side problem

A 5xx does not automatically mean your network device is down. It may be the controller, API service, or upstream process.

Headers matter

APIs often require headers.

Catalyst Center example:

X-Auth-Token: <token>
Content-Type: application/json

RESTCONF JSON example:

Accept: application/yang-data+json
Content-Type: application/yang-data+json

Wrong or missing headers can produce 401, 403, 406, or 415 responses.

Catalyst Center response pattern

A Catalyst Center inventory response may include a top-level key such as response.

{
  "response": [
    {
      "hostname": "HQ-SW1",
      "managementIpAddress": "10.10.10.12",
      "platformId": "C9300-48P",
      "reachabilityStatus": "Reachable"
    }
  ],
  "version": "1.0"
}

A script might read it like this:

payload = response.json()
for device in payload.get("response", []):
    print(device["hostname"], device["reachabilityStatus"])

If the status code is 200 but the list is empty, the API worked. Your filter may have matched no devices.

RESTCONF response pattern

RESTCONF uses YANG-modeled resources. A GET request can return JSON.

Example request:

curl --cacert "$RESTCONF_CA_BUNDLE" -u "$RESTCONF_USER:$RESTCONF_PASS" \
  -H 'Accept: application/yang-data+json' \
  https://10.10.10.11/restconf/data/ietf-interfaces:interfaces

Example response:

{
  "ietf-interfaces:interfaces": {
    "interface": [
      {
        "name": "GigabitEthernet1",
        "description": "WAN uplink",
        "type": "iana-if-type:ethernetCsmacd",
        "enabled": true
      }
    ]
  }
}

Read the model prefix and path:

ietf-interfaces:interfaces

That tells you the data came from the ietf-interfaces model namespace.

Python response handling

A clean script checks both status code and payload.

import os
import requests

ca_bundle = os.environ.get("REQUESTS_CA_BUNDLE", True)

response = requests.get(
    "https://10.10.10.11/restconf/data/ietf-interfaces:interfaces",
    auth=(os.environ["RESTCONF_USER"], os.environ["RESTCONF_PASS"]),
    headers={"Accept": "application/yang-data+json"},
    timeout=10,
    verify=ca_bundle
)

if response.status_code == 200:
    data = response.json()
    interfaces = data.get("ietf-interfaces:interfaces", {}).get("interface", [])
    for interface in interfaces:
        print(interface["name"], interface.get("enabled"))
elif response.status_code == 202:
    print("Accepted: poll the task/job endpoint before declaring success")
elif response.status_code == 204:
    print("Success with no response body")
elif response.status_code == 401:
    print("Authentication failed")
elif response.status_code == 404:
    print("Resource not found")
else:
    print(f"Unexpected status: {response.status_code}")
    print(response.text)

This is exam-useful because the logic maps response codes to troubleshooting conclusions.

Do not call .json() blindly on 204 No Content; there is no body to parse. Do not treat 202 Accepted as completion; many controller operations return a task identifier and require follow-up polling.

Interpreting common failures

Failure: 401 Unauthorized

Likely causes:

• wrong username/password;
• missing token;
• expired token;
• token sent in the wrong header;
• authentication method not supported.

Do not troubleshoot routing first. Check auth.

Failure: 403 Forbidden

Likely causes:

• user is authenticated but lacks permissions;
• role-based access control blocks the action;
• API token is valid but not authorized for that endpoint.

Failure: 404 Not Found

Likely causes:

• wrong endpoint path;
• wrong API version;
• unsupported feature;
• wrong resource ID;
• RESTCONF model path is incorrect.

Failure: 415 Unsupported Media Type

Likely causes:

• missing Content-Type header;
• using regular application/json when RESTCONF expects application/yang-data+json;
• sending XML to an endpoint expecting JSON.

Failure: 202 Accepted

This is not a final success. It often means the controller accepted a task and you must poll a task endpoint or check job status.

For controller workflows, the correct evidence chain is usually: submit request, read task ID, poll task/job status, then verify the intended network object changed.

Lab: read status code and payload

Goal

Practice interpreting REST API results without guessing.

Task 1: create a fake response parser

Create interpret_response.py:

responses = [
    {
        "status": 200,
        "payload": {"response": [{"hostname": "SW1", "reachabilityStatus": "Reachable"}]}
    },
    {
        "status": 401,
        "payload": {"message": "Unauthorized"}
    },
    {
        "status": 204,
        "payload": None
    },
    {
        "status": 415,
        "payload": {"error": "Unsupported Media Type"}
    }
]

for item in responses:
    status = item["status"]
    payload = item["payload"]

    if status == 200:
        print("Success with body")
        print(payload)
    elif status == 204:
        print("Success with no response body")
    elif status == 401:
        print("Authentication problem")
    elif status == 415:
        print("Check Content-Type header")
    else:
        print(f"Unhandled status: {status}")

Run it:

python3 interpret_response.py

Task 2: RESTCONF GET test

If you have an IOS XE lab device with RESTCONF enabled:

curl --cacert "$RESTCONF_CA_BUNDLE" -i -u "$RESTCONF_USER:$RESTCONF_PASS" \
  -H 'Accept: application/yang-data+json' \
  https://10.10.10.11/restconf/data/ietf-interfaces:interfaces

The -i flag shows headers and status code.

You may see curl -k in quick self-signed labs, but that disables certificate validation. Use a trusted CA bundle when practicing the safe pattern.

Task 3: break auth on purpose

Run the same command with a wrong password.

Write down:

Status code:
  Payload/body:
  What it means:
  Fix:

Task 4: break the media type

Try a request with the wrong content type on a method that sends data. Note whether your device returns 400, 406, or 415; platforms vary. The important skill is connecting the code to the cause.

What to memorize

200 OK = success with body
201 Created = created resource
202 Accepted = accepted, may need task polling
204 No Content = success, empty body
400 Bad Request = malformed input
401 Unauthorized = authentication problem
403 Forbidden = permission problem
404 Not Found = endpoint/resource path problem
409 Conflict = state conflict
415 Unsupported Media Type = wrong Content-Type/payload format
500+ = server/controller side problem

Exam-ready summary

Always read status code and payload together. First decide whether the problem is success, authentication, authorization, path, payload, media type, conflict, or server-side failure. Then inspect the JSON body for the specific field, task ID, error message, device list, or model namespace. That is the ENCOR skill.

Sources used

• Cisco ENCOR 350-401 v1.2 exam topics: https://learningcontent.cisco.com/documents/marketing/exam-topics/350-401-ENCORE-v1.2.pdf
• RFC 8040, RESTCONF Protocol: https://datatracker.ietf.org/doc/html/rfc8040
• Cisco Catalyst Center API documentation: https://developer.cisco.com/docs/catalyst-center/