Z/OS Connect API returns HTTP 403

Z/OS Connect API returns HTTP 403 means the HTTP layer worked but something above it rejected the call. Read the status code literally - it tells you which layer said no.

What it means

• z/OS Connect EE has two roles: API provider exposes z/OS assets as REST, API requester lets z/OS call out to REST services.
• 401 means missing or bad credentials, 403 means authenticated but not authorized, 404 means wrong URI or service not deployed, 500 means the backend failed.
• A 200 response carrying a business error inside the payload means transport succeeded and application logic rejected the request.

Common causes

• Expired or wrong credentials or OAuth token on the caller side, giving 401.
• Caller ID missing access to the SAF-protected service resource, giving 403.
• Service archive (.sar) not deployed, or deployed to the wrong z/OS Connect server, giving 404.
• Backend CICS transaction abend or Db2 SQL error bubbling up as 500.
• Request JSON missing a required field or using a wrong field name after a schema change.
• Gateway or proxy timeout set shorter than the backend transaction time, so the caller gives up while z/OS keeps working.

How to diagnose

• Reproduce with curl -v to capture the exact status code, headers, and response body.
• Check the z/OS Connect server messages.log for the request ID and the mapped backend error.
• For 403, read the SAF denial message in the server log - it names the exact resource that was denied.
• For 500, trace into the backend: the CICS CSMT log or the SQLCODE carried in the response payload.
• Compare the request payload field by field against the OpenAPI document of the deployed service version.

How to fix it

• Refresh the credentials or token; renew OAuth tokens before expiry in long-running flows.
• Grant the caller ID access to the service resource or correct the mapping in server.xml.
• Deploy the correct .sar to the z/OS Connect server and refresh the service.
• Fix the backend error itself - the 500 is only the messenger.
• Align the caller payload with the deployed schema, and version the API whenever fields change.

Example: Reproduce a z/OS Connect failure with curl

The -v output shows the real status code and the response body, which usually names the backend error.

Interview tip

• Q: z/OS Connect returns 403 for a call that worked the day before. Z/OS Connect API returns HTTP 403 - what changed?
• A: 403 means authentication passed but authorization failed, so I look for what changed on the access path: an expired credential mapping, a SAF profile change, or a redeployed service with a different resource name. I check the server log for the exact SAF denial and compare the deployed service archive version with the previous day.

Prevention checklist

• Version every API and keep the OpenAPI document next to the deployed .sar so callers code against the truth.
• Alert on 401, 403, and 500 rate spikes per service instead of hearing about them from callers.
• Set gateway timeouts longer than the slowest backend transaction plus margin.
• Make retried calls idempotent so a gateway timeout cannot double-post a business transaction.