Skip to content

Custom Error and Message

Overview

Custom error and message is an optional section on supported gateway policies. When a policy fails or triggers at the API Gateway, it lets you override the default HTTP status code, error code, and error message returned to the client.

Enable it with the Custom error and message toggle at the bottom of a policy create or edit modal.

This feature is not the same as Raise Fault:

Feature Custom error and message Raise Fault
Trigger A supported policy fails (validation, quota, throttling, etc.) Configurable rule conditions match
Scope Optional section inside another policy Standalone Request/Response policy
Configuration Select platform default errors; override status, code, and message JSON rules + fault payload 
flowchart LR
    Request[API Request] --> Policy[Gateway Policy executes]
    Policy -->|Success| Backend[Forward to backend]
    Policy -->|Failure| DefaultErr[Default error response]
    Policy -->|Failure + custom enabled| CustomErr[Overridden status code message]

When to Use Custom Error and Message

Use this feature when:

  • You need consistent, client-friendly error responses when a specific policy fails
  • Default platform error messages do not match your API error contract
  • Different error codes or HTTP status codes should be returned for the same policy failure type

When Not to Use Custom Error and Message

Avoid relying on it when:

  • You need conditional faults based on request/response attributes (use Raise Fault)
  • The policy type has no platform default errors (the section is hidden)
  • Complex fault logic belongs in backend services

Prerequisites

  • Active Yappes platform account
  • API Manager access
  • Permission to create and manage gateway policies
  • A supported policy open in create or edit mode

Where It Appears

Surface Path
API Level (endpoint) My APIs → edit API → Step 2 → Endpoint Details → policy tab → Create/Edit policy modal
Subscription Level Gateway Control → Gateway Policies → Create/Edit policy modal
Monetization Limit Check Subscription policy modal (monetization threshold)

The section appears at the bottom of the policy modal, below primary policy settings.

When you enable the section, Select error lists the platform default errors available for that policy type.

If no default errors exist for the policy type, the UI shows:

This policy doesn't have custom message/default error.

Configuration Fields

UI field Required when enabled Validation
Custom error and message (toggle) — Enables override
Select error Yes Dropdown of platform default errors for this policy type
HTTP status code (read-only default block) — Shows platform default
Error code (read-only default block) — Shows platform default
Error message (read-only default block) — Shows platform default
HTTP status code (custom block) Yes 3-digit numeric; first digit 1–5
Custom error code Yes Required text
Custom error message Yes Required text

Items in Select error show a Default or Customized badge.

Use Add Custom message to add override blocks for additional default error codes (up to the number of available defaults).

Step-by-Step

  1. Open a supported policy in create or edit mode (endpoint tab or Gateway Policies page).
  2. Complete the primary policy configuration.
  3. Scroll to Custom error and message.
  4. Enable the toggle.
  5. Select an error from Select error.
  6. Review the read-only default HTTP status code, Error code, and Error message.
  7. Enter custom values in the Custom message block.
  8. Optionally click Add Custom message to override additional error codes.
  9. Save the policy.

Note

Save is blocked when Custom error and message is enabled but custom blocks fail validation (missing status code, error code, or message).

Supported Policies

API Level (endpoint policy modals)

Policy Documentation
Advanced Routing Advance Routing Policy
Caching Cache Policy
Transformation Transformation Policy
Mock API Response Mocking Policy
Verify Headers Verify Headers Policy
Schema Validation Schema Validation Policy
Custom Plugin Custom Plugin Policy
Encryption & Decryption Encryption and Decryption Policy
API Quota Check API Quota Check Policy
JSON Threat Protection JSON Threat Protection Policy
XML Threat Protection XML Threat Protection Policy
Regex Threat Protection Regex Threat Protection Policy
Payload Capture Payload Capture Policy

Subscription Level (Gateway Policies page)

Policy Documentation
Throttling Throttling Policy
Blacklist IP Address Blacklist IP Address Policy
Whitelist IP Address Whitelist IP Address Policy
Message Signature Message Signature Policy
Load Balancing Load Balancing Policy
Advanced Routing Advance Routing Policy
Transformation Transformation Policy
Mock API Response Mocking Policy
Verify Headers Verify Headers Policy
Schema Validation Schema Validation Policy
Custom Plugin Custom Plugin Policy
Encryption & Decryption Encryption and Decryption Policy
Mutual TLS (mTLS) Mutual TLS Configuration Policy
CORS CORS Policy
Raise Fault Raise Fault Policy
API Quota Check API Quota Check Policy
JSON / XML / Regex Threat Protection respective threat protection docs
Payload Capture Payload Capture Policy
Monetization Limit Check Configure on subscription policy threshold modal

What Happens When Enabled

When enabled and saved, the gateway returns your custom HTTP status code, error code, and message for the selected default error(s) instead of the platform defaults.