Error handling

Proper error handling is essential for building robust and user-friendly applications that interact with the Partner Services API. This section provides an overview of the error handling mechanisms provided by the API, common error responses, and best practices for managing errors in your application.

Common HTTP Status Codes

The Partner Services API uses standard HTTP status codes to indicate the success or failure of an API request. Here are the most common status codes you might encounter:

• 200 OK: The request was successful, and the server returned the requested data.

• 201 Created: The request was successful, and a new resource was created.

• 400 Bad Request: The server could not understand the request due to invalid syntax.

• 401 Unauthorized: Authentication failed due to invalid API key or missing credentials.

• 403 Forbidden: The client does not have access rights to the content.

• 404 Not Found: The server can not find the requested resource.

• 422 Unprocessable Entity: The request was well-formed but was unable to be followed due to semantic errors.

• 500 Internal Server Error: The server encountered an unexpected condition that prevented it from fulfilling the request.

Example Error Responses

Here are examples of error responses that you might encounter when using the Partner Services API:

400 Bad Request:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "00-abc123def456gh-ijkl7890mn12op34qr56st78",
  "errors": {
    "applicationNumber": [
      "The application number is required."
    ]
  }
}

401 Unauthorized:

{
  "type": "https://tools.ietf.org/html/rfc7235#section-3.1",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication failed due to invalid API key."
}

404 Not Found:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  "title": "Not Found",
  "status": 404,
  "traceId": "00-abc123def456gh-ijkl7890mn12op34qr56st78",
  "detail": "The requested resource could not be found."
}

500 Internal Server Error:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.6.1",
  "title": "Internal Server Error",
  "status": 500,
  "traceId": "00-abc123def456gh-ijkl7890mn12op34qr56st78",
  "detail": "An unexpected error occurred. Please try again later."
}

Best Practices for Error Handling

1. Log Errors:

   • Always log errors in your application to help diagnose and fix issues. Include relevant information such as status codes, error messages, and stack traces.

2. Display User-Friendly Messages:

   • Avoid displaying raw error messages to end-users. Instead, provide user-friendly messages and instructions on how to proceed or contact support.

3. Retry Mechanism:

   • Implement a retry mechanism for transient errors such as network issues or rate limiting. Use exponential backoff to avoid overwhelming the server.

4. Graceful Degradation:

   • Design your application to degrade gracefully when an error occurs. For example, if a non-critical API call fails, continue to provide as much functionality as possible.

5. Validation Errors:

   • Handle validation errors (HTTP 400) by providing clear feedback to the user about what went wrong and how to correct it.

6. Authentication Errors:

   • Prompt the user to re-authenticate or provide correct credentials if a 401 Unauthorized error occurs.

7. Resource Not Found:

   • Handle 404 Not Found errors by informing the user that the requested resource does not exist or is no longer available.

8. Server Errors:

   • For 500 Internal Server Error responses, inform the user that an error occurred and that the issue is being looked into. Optionally, provide a way to report the error.

Example in .NET

Here’s an example of how to handle errors in a .NET application using HttpClient:

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using Newtonsoft.Json.Linq;

namespace PartnerServicesApiExample
{
    class Program
    {
        private static readonly HttpClient client = new HttpClient();

        static async Task Main(string[] args)
        {
            var apiKey = "YOUR_API_KEY";
            client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);

            var applicationId = 123;
            var response = await client.GetAsync($"https://api.partner-services.com/application/{applicationId}");

            if (response.IsSuccessStatusCode)
            {
                var responseData = await response.Content.ReadAsStringAsync();
                Console.WriteLine(responseData);
            }
            else
            {
                await HandleError(response);
            }
        }

        static async Task HandleError(HttpResponseMessage response)
        {
            var statusCode = (int)response.StatusCode;
            var errorContent = await response.Content.ReadAsStringAsync();
            var errorDetails = JObject.Parse(errorContent);

            Console.WriteLine($"Error: {statusCode}");
            Console.WriteLine($"Details: {errorDetails["detail"]}");

            switch (statusCode)
            {
                case 400:
                    Console.WriteLine("Bad Request: Please check the input parameters.");
                    break;
                case 401:
                    Console.WriteLine("Unauthorized: Please check your API key.");
                    break;
                case 404:
                    Console.WriteLine("Not Found: The requested resource was not found.");
                    break;
                case 500:
                    Console.WriteLine("Internal Server Error: Please try again later.");
                    break;
                default:
                    Console.WriteLine("An unexpected error occurred.");
                    break;
            }
        }
    }
}

By following these best practices and utilizing the provided examples, you can effectively handle errors in your application and provide a better user experience.