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.

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

Management API endpoints 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.

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