Error References

BessaPay API uses the RFC-9457 Problem Details format for error responses. This page provides a comprehensive reference of all error types returned by the API and how to handle them.

Error Format

All error responses follow the standard RFC-9457 Problem Details format, which provides a consistent structure for error information. This makes error handling more predictable and enables better integration with client applications.

Example Error Response

1{
2  "type": "https://bessapay.net/errors/validation-error",
3  "title": "Validation Error",
4  "status": 400,
5  "detail": "The amount field must be a positive number",
6  "instance": "/api/v1/transactions",
7  "errorCode": "VALIDATION_ERROR",
8  "timestamp": "2023-06-15T10:15:30Z"
9}

Standard Fields

Field	Description	Example
type	A URI reference that identifies the problem type	`https://bessapay.net/errors/not-found`
title	A short, human-readable summary of the problem type	Resource Not Found
status	The HTTP status code	`404`
detail	A human-readable explanation specific to this occurrence of the problem	The transaction with ID 'abc123' could not be found
instance	A URI reference that identifies the specific occurrence of the problem	`/api/v1/transactions/abc123`
errorCode	A BessaPay-specific error code for programmatic handling	`NOT_FOUND`
timestamp	When the error occurred (ISO 8601 format)	`2023-06-15T10:15:30Z`

Error Types

Click on any error type below to view detailed documentation, including common causes, how to fix, and code examples for handling each error.

Error Type URI	Error Code	HTTP Status	Description
https://bessapay.net/errors/bad-request	`BAD_REQUEST`	400	The request was malformed or contained invalid parameters
https://bessapay.net/errors/unauthorized	`UNAUTHORIZED`	401	Authentication credentials are missing or invalid
https://bessapay.net/errors/forbidden	`FORBIDDEN`	403	The authenticated user does not have permission to access the resource
https://bessapay.net/errors/not-found	`NOT_FOUND`	404	The requested resource does not exist
https://bessapay.net/errors/validation-error	`VALIDATION_ERROR`	400	The request data failed specific validation rules
https://bessapay.net/errors/too-many-requests	`TOO_MANY_REQUESTS`	429	The client has sent too many requests in a given time period
https://bessapay.net/errors/server-error	`SERVER_ERROR`	500	An unexpected error occurred on the server
https://bessapay.net/errors/authentication-error	`AUTHENTICATION_ERROR`	401	Specific authentication process error (token format, etc.)
https://bessapay.net/errors/account-already-exists	`ACCOUNT_ALREADY_EXISTS`	409	An account with the provided identifier already exists
https://bessapay.net/errors/user-not-found	`USER_NOT_FOUND`	404	The specified user could not be found
https://bessapay.net/errors/malformed-order	`MALFORMED_ORDER`	400	The order data is invalid or incomplete
https://bessapay.net/errors/access-denied	`ACCESS_DENIED`	403	The requested action is not allowed for business reasons

Handling Errors

When interacting with the BessaPay API, it's important to implement proper error handling to ensure a smooth experience for your users. Here are some best practices:

Use the type field for programmatic handling

The type field is designed to be a stable identifier for the error category. Use it to determine the appropriate error handling logic in your application.

Display user-friendly messages

The detail field provides a human-readable description of the error. Use this to display helpful information to your users.

Implement retry logic for appropriate errors

Some errors, like rate limiting (429) or temporary server issues (500), can be resolved by retrying the request after a delay. Implement exponential backoff for these scenarios.

Check validation errors thoroughly

For validation errors, the response might include an errors array with field-specific validation failures. Map these to your form fields to provide inline feedback.

Log error details for troubleshooting

Include the instance and timestamp fields in your logs to help correlate client-side errors with server logs when troubleshooting issues.

Error Handling Example

1// Example of comprehensive error handling
2async function handleApiRequest(endpoint, options = {}) {
3  try {
4    const response = await fetch(`https://api.semuni.com/v1${endpoint}`, {
5      ...options,
6      headers: {
7        'Authorization': `Bearer ${apiKey}`,
8        'Content-Type': 'application/json',
9        ...options.headers
10      }
11    });
12    
13    if (!response.ok) {
14      const errorData = await response.json();
15      
16      // Log the error for debugging
17      console.error(`API Error: ${errorData.type} - ${errorData.detail}`, {
18        instance: errorData.instance,
19        timestamp: errorData.timestamp,
20        status: errorData.status
21      });
22      
23      // Handle based on error type
24      switch (errorData.type) {
25        case 'https://bessapay.net/errors/validation-error':
26          return handleValidationError(errorData);
27          
28        case 'https://bessapay.net/errors/unauthorized':
29        case 'https://bessapay.net/errors/authentication-error':
30          return handleAuthError(errorData);
31          
32        case 'https://bessapay.net/errors/too-many-requests':
33          return handleRateLimitError(errorData);
34          
35        case 'https://bessapay.net/errors/server-error':
36          return handleServerError(errorData);
37          
38        default:
39          // Generic error handling
40          throw new Error(errorData.detail || 'An unexpected error occurred');
41      }
42    }
43    
44    return await response.json();
45  } catch (error) {
46    // Handle network errors or other exceptions
47    console.error('Request failed:', error);
48    throw error;
49  }
50}