Define Custom API Response Status Codes
You can define custom HTTP response status codes and error messages in your custom API code. This allows you to control how your API communicates errors back to the client, instead of relying on default responses.
How it works
- Use the
BaseResponsetype (from theConga.Platform.Extensibility.CustomCode.Library.Modelsnamespace) in your custom code. - Set the HTTP status code and error details (such as code, reason, and message) in the
BaseResponse. - The system reads these values and includes them in the final API response.
Example: Using BaseApiResponse
This example demonstrates how to return a default response and a custom error response using the
BaseApiResponse model. You can test custom responses using the BaseApiResponse class, available under:Conga.Platform.Extensibility.CustomCode.Library.ModelsSample Custom Code
using Conga.Platform.Common.Models;
using Conga.Platform.Extensibility.CustomCode.Library.Models;
using Conga.Platform.Extensibility.CustomCode.Library;
using System.Collections.Generic;
using System.Net;
using System.Threading;
namespace CustomApi.Template
{
public class SampleAccount : CodeExtensibility
{
/// <summary>
/// A test method to verify cancellation token handling.
/// </summary>
/// <param name="cancellationToken">The token to monitor for cancellation requests.</param>
/// <returns>Returns the string "testing".</returns>
public string TestAsync(CancellationToken cancellationToken)
{
ThrowIfCancellationRequested(cancellationToken);
return "testing";
}
/// <summary>
/// A test method that returns a sample error response.
/// </summary>
/// <param name="cancellationToken">The token to monitor for cancellation requests.</param>
/// <returns>Returns a <see cref="BaseApiResponse{object}"/> with a sample error message.</returns>
public BaseApiResponse<object> TestErrorAsync(CancellationToken cancellationToken)
{
ThrowIfCancellationRequested(cancellationToken);
var errors = new List<string>()
{
"Bad request sample error"
};
return ErrorResponse(null, HttpStatusCode.BadRequest, errors, cancellationToken);
}
#region Private methods
/// <summary>
/// Creates an error response with the specified data, status, and messages.
/// </summary>
/// <param name="data">The data to include in the response.</param>
/// <param name="httpStatus">The HTTP status code for the response.</param>
/// <param name="messages">A list of error messages.</param>
/// <param name="cancellationToken">The token to monitor for cancellation requests.</param>
/// <returns>Returns a <see cref="BaseApiResponse{object}"/> that represents the error.</returns>
private BaseApiResponse<object> ErrorResponse(object data, HttpStatusCode httpStatus, List<string> messages, CancellationToken cancellationToken)
{
ThrowIfCancellationRequested(cancellationToken);
return new BaseApiResponse<object>(data, messages, httpStatus)
{
Success = false,
StatusCode = httpStatus
};
}
#endregion
}
}
How it Works
- TestAsync:Returns a standard response with
Data = "testing"andStatusCode = 200. - TestErrorAsync: Returns a custom response with
StatusCode = 400and a custom error message.
Response Comparison
With Custom Response (
TestErrorAsync){
"Data": null,
"StatusCode": 400,
"Errors": [
"Sample error message for a bad request"
]
}
Without Custom Response (
TestAsync){
"Data": "testing",
"StatusCode": 200,
"Errors": []
}