Error Handling

Overview

The Management API uses standard HTTP status codes. Management endpoints (CRUD, deployment, settings, and similar) return errors in a consistent JSON envelope. The token endpoint (POST /apiops/auth/token) uses a separate OAuth-style format — see Token endpoint errors below.

Info

This page describes the envelope used by the endpoints that existed before the newer common contract. Newer endpoints return a body that carries a correlationId alongside a stable, machine-readable errorKey, and they use 402, 403, 404, 409 and 503 where the endpoints on this page would answer 400. If a response contains a correlationId, read Common Contract instead of this page.

A few of the endpoints on this page answer with an RFC 7807 problem body instead of the envelope below — it carries type, path, a numeric status, and an errorKey naming the reason. That shape is not limited to validation failures: it is also used for a refusal the caller is not permitted to make (403), an object it may not see or that does not exist (404), and a request that conflicts with the current server state (409). The errorKey is the same stable key in every one of those cases, so branch on it the same way; it is the key the user interface translates.

Two error paths that were previously reported as 500 Internal Server Error — a project that cannot be found and a token that cannot be validated, on endpoints without their own error handling — are now reported as 400, 401, 403 or 404. Automation that retries on 5xx should be reviewed.

HTTP Status Codes

Status Code	Meaning	Typical use in Management API
200	OK	Request succeeded
400	Bad Request	Validation failure, missing parameter, resource not found in project context, insufficient project permission
401	Unauthorized	Missing, invalid, or expired Personal API Access Token
500	Internal Server Error	Unexpected server error

Note

The endpoints described on this page generally do not return 403 Forbidden or 404 Not Found for missing projects or resources. Those cases are reported as 400 Bad Request with a descriptive resultMessage. A small number of specialized endpoints may return 404 with an empty body. Endpoints that follow the Common Contract behave differently: there, a missing or inaccessible object is always 404.

Management API error response format

All Management API endpoints (everything under /apiops/ except the token endpoint) return errors in this format:

{
  "status": "FAILURE",
  "resultMessage": "Human-readable error message"
}

Field	Type	Description
status	string	Always FAILURE on error
resultMessage	string	Exact error text from the server

On success, the same envelope uses status: "SUCCESS" and may include resultList, resultCount, resultMessage, or operation-specific fields.

400 Bad Request

Returned when request validation fails, a referenced resource does not exist in the project, or the authenticated user lacks the required project permission.

Example responses

{
  "status": "FAILURE",
  "resultMessage": "projectName value can not be empty!"
}

{
  "status": "FAILURE",
  "resultMessage": "Project (MyProject) is not found!"
}

{
  "status": "FAILURE",
  "resultMessage": "User does not have required permission for this operation!"
}

{
  "status": "FAILURE",
  "resultMessage": "ApiProxy (name: petstore-api) is already exist!"
}

Common causes

• Missing or empty path, query, or body fields
• Invalid field values or unsupported enum values
• Project, API proxy, credential, or other resource not found in the given project
• User lacks the required permission for the operation in that project

401 Unauthorized

Returned when the Personal API Access Token is missing, invalid, or expired.

Example responses

{
  "status": "FAILURE",
  "resultMessage": "Empty Key! Client must be authenticated to access this resource."
}

{
  "status": "FAILURE",
  "resultMessage": "Token is not valid!"
}

{
  "status": "FAILURE",
  "resultMessage": "Token was expired!"
}

Common causes

• Missing Authorization header
• Invalid or revoked token
• Expired token

500 Internal Server Error

Returned for unexpected failures.

Example response

{
  "status": "FAILURE",
  "resultMessage": "An unexpected error occurred"
}

Token endpoint errors

POST /apiops/auth/token uses OAuth-style error fields (not status / resultMessage):

{
  "status": "FAILURE",
  "resultMessage": "Bad credentials"
}

See Authentication and Authentication API for token request and error details.

Error handling best practices

1. Check HTTP status first

Always inspect the HTTP status code before parsing the body:

if response.status_code == 200:
    process_success(response.json())
else:
    handle_error(response.status_code, response.json())

2. Read resultMessage on Management API errors

For Management API endpoints, extract the human-readable message from resultMessage:

body = response.json()
if body.get("status") == "FAILURE":
    logger.error(body.get("resultMessage", "Unknown error"))

3. Handle 401 by refreshing the token

When you receive 401 with a token-related resultMessage, obtain a new Personal API Access Token and retry once.

4. Retry transient 500 errors

Implement limited retry with backoff for 500 responses and network failures.

5. Log status and message together

logger.error("API error %s: %s", response.status_code, body.get("resultMessage"))

Troubleshooting

401 Unauthorized

• Verify the Authorization: Bearer header is present
• Confirm the token has not expired or been revoked
• Create a new token if needed

400 Bad Request

• Read resultMessage — it states the exact validation or not-found reason
• Verify path parameters (project name, resource name) are correct
• Confirm your user has the required permission in that project
• Validate the request body against the endpoint documentation

500 Internal Server Error

• Retry the request with backoff
• Contact support if the error persists

Next Steps

• Explore the API reference - Complete API endpoint documentation