Response codes

HTTP status codes and error handling for the Precium API.

‍

HTTP Status Codes

‍

Success Responses

200 OK

Returned for successful GET requests and updates.

‍

JSON

{
  "id": "8f4a6b0f-fa9b-4f45-8e19-b75c1a70432a",
  "status": "COMPLETED",
  ...
}

‍

201 Created

Returned when a resource is successfully created.

‍

JSON

{
  "id": "new-resource-id",
  "status": "PENDING",
  ...
}

‍

204 No Content

Returned when a resource is successfully deleted. No response body.

‍

Error Responses

400 Bad Request

Invalid request data. Check required fields and formats.

‍

JSON

{
  "value": {
    "Message": "Validation error: field 'accountNumber' is required"
  },
  "statusCode": 400
}

‍

Common causes:

• Missing required fields
• Invalid field formats
• Invalid enum values
• Business rule violations

‍

401 Unauthorized

Invalid or expired access token.

‍

JSON

{
  "message": "Unauthorized"
}

‍

Resolution: Request a new access token.

‍

403 Forbidden

Insufficient permissions for the requested operation.

‍

JSON

{
  "message": "Forbidden"
}

‍

Resolution: Contact Precium support to verify account permissions.

‍

404 Not Found

Requested resource does not exist.

‍

JSON

{
  "message": "Resource not found"
}

‍

Common causes:

• Invalid resource ID
• Resource deleted or expired

‍

409 Conflict

Resource conflict, typically duplicate data.

‍

JSON

{
  "message": "Duplicate external reference"
}

‍

Common causes:

• Duplicate externalReference
• Duplicate contractReference

‍

500 Internal Server Error

Server-side error.

‍

JSON

{
  "message": "Internal server error"
}

‍

Resolution: Contact Precium support with request details.

‍

Mandate Status Codes

EFT Mandate Statuses

‍

DebiCheck Mandate Statuses

‍

Collection Status Codes

‍

Unpaid Reason Codes

When a collection returns UNPAID, additional information may include:

‍

‍

Payment Status Codes

‍

Bank Account Verification Codes

When verifyAccount: true fails:

‍

JSON

{
  "value": {
    "Message": "Debtor account verification failure: details={\"AccountExists\":true,\"AccountIsOpen\":false,\"AccountTypeMatches\":null,\"IdNumberMatches\":null,\"AccountAcceptsDebits\":null}"
  },
  "statusCode": 400
}

‍

‍

Error Handling Best Practices

Retry Logic

JSX

async function apiRequest(options, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(options.url, options);

      if (response.status === 401) {
        // Refresh token and retry
        await refreshToken();
        continue;
      }

      if (response.status >= 500) {
        // Server error - wait and retry
        await sleep(attempt * 1000);
        continue;
      }

      return response;
    } catch (error) {
      if (attempt === maxRetries) throw error;
      await sleep(attempt * 1000);
    }
  }
}

‍

Logging

Log all API responses for debugging:

‍

JSX

console.log({
  timestamp: new Date().toISOString(),
  endpoint: response.url,
  status: response.status,
  requestId: response.headers.get('x-request-id'),
  body: await response.json()
});

‍

Error Mapping

Map API errors to user-friendly messages:

‍

JSX

const errorMessages = {
  400: 'Invalid request data. Please check your input.',
  401: 'Session expired. Please log in again.',
  403: 'You do not have permission for this action.',
  404: 'The requested resource was not found.',
  409: 'This reference already exists.',
  500: 'An unexpected error occurred. Please try again later.'
};

‍

Contact Support

If you encounter a 500 status code or persistent errors:

1. Note the request details (endpoint, payload, timestamp)
2. Check for any x-request-id in response headers
3. Contact Precium support with this information

‍

Email: support@precium.com