Errors & Conventions
Shared conventions across the OptoSoft Retapos API — status codes, error handling, request format, pagination and versioning.
HTTP status codes
The API uses standard HTTP status codes to signal the result of a request.
| Code | Meaning |
|---|---|
| 200 | Success — the response body contains the result. |
| 400 | Bad request — a parameter or body field is missing or invalid. |
| 401 | Unauthorized — the token is missing, expired or invalid. Re-authenticate. |
| 403 | Forbidden — the account lacks permission for this resource. |
| 404 | Not found — the resource or record does not exist. |
| 409 | Conflict — the request conflicts with the current state (e.g. duplicate). |
| 429 | Too many requests — slow down and retry with backoff. |
| 500 | Server error — retry later; if it persists, contact support. |
Request format
- All paths are relative to the base URL
https://app.opto-soft.com/global/api-v1. - Send and accept
application/json. Include theAuthorization: Bearerheader on every authenticated call. - List and search operations are typically
POSTendpoints that take a search/filter body rather than query strings.
Encrypted payload envelopes
Several endpoints exchange encrypted DTO envelopes — their schemas are prefixed Encrypted…
in the API reference
(for example EncryptedCustomerModel, EncryptedInvoiceListDto).
The encryption contract for these envelopes is provided to partners during API onboarding.
Pagination
List endpoints return paged results wrapped in a paged response object (schemas suffixed
…PagedApiResponse / …PagedResult).
Pass the page and page-size fields defined by each search request body, and read the total count from the paged wrapper to iterate through all records.
Versioning
The API is versioned in the URL path (/global/api-v1). Backward-compatible additions —
new endpoints, new optional fields — are made within v1. Breaking changes are introduced
under a new version path so existing integrations keep working. This documentation is reviewed against the live
specification monthly.