Error Handling

Last update: September 19, 2025

Return code

All API endpoints that are in this document may return the following codes:

Return codes	Status	Meaning	Description
200	OK	Success	The request was correct, so the returned message contains the response message
400	KO	Bad Request	Mandatory parameter is missing. For example: Header `X-Oney-Authorization` is missing.
401	KO	Unauthorized.	Unauthorized request.
403	KO	Forbidden	Invalid API KEY or API quota exceeded.
404	KO	Not Found	The API does not exist, unknown command.
408	KO	Request Time-out	Execution period of the service is too long.
409	KO	Conflict	The external reference must be unique.
429	KO	Too Many Requests	Rate limit is reached.
499	KO	Client Closed Request	Your time out is too short. We have set our time out to 10 secondes
500	KO	Internal Server Error	Failed to process the request.
503	KO	Service Unavailable	Service is not available.
504	KO	Gateway Timeout

Errors format

When a HTTP 400 code is returned, the nature of the errors (functional errors only) encountered on each of the fields will be returned in the following form :

Open API specification

Error:
  type: object
  description: 'Object containing data regarding the error'
  properties:
    language_code:
        type: string
        description: Language code in [ISO 639-1](https://www.iso.org/iso-639-language-codes.html) format
        maxLength: 2
    error_list:
        type: array
        description: The list of error details.
        items:
            type: object
            description: The error details.
            properties:
                error:
                    description: An error detail.
                    type: object
                    properties:
                        field:
                            type: string
                            description: The error detail value (the element in the request that lead to an error).
                            maxLength: 100
                        error_code:
                            type: string
                            description: The error detail code.
                            maxLength: 10
                        error_label:
                            type: string
                            description: The error detail message.
                            maxLength: 1000

Exemple of error returned

{
  "language_code": "EN",
  "error_list": [
    {
      "error": {
        "field": "purchase.external_reference_type",
        "error_code": "ERR_02",
        "error_label": "Field size must be less than 128 characters"
      }
    }
  ]
}

Description of error list

Service Payment

Error code	Error label	HTTP CODE
ERR_01	The field is mandatory	400
ERR_02	Field size must be less than %s characters	400
ERR_03	Field format is invalid %s	400
ERR_03	The customer email doesn't exist, is full or isn't responding	400
ERR_04	Field value is invalid %s	400
ERR_05	The limits of a business transaction are exceeded	400
ERR_06	A business transaction does not have the right type	400
ERR_07	Application processing failure	400
ERR_07	No business transaction code or version in database: Business transaction not transmitted for a route with fallback and not parameterized in database	400
ERR_07	Problem setting up the journey	400
ERR_07	JSON deserialization problem	400
ERR_10	The external reference is already used for another file.	409
ERR_19	Failure to process request: Unknown brand name	409
ERR_23	The field type is not compatible with the one passed in parameter	400
ERR_25	Mandatory field Loyalty barcode not filled in	400
ERR_25	Only if the merchant is set up to use loyalty	400
ERR_26	A file already exists with the same references and creation date	400

Service Confirm

Error code	Error label	HTTP CODE
ERR_05	Mandatory URL Reference field not filled in	400
ERR_06	The mandatory Merchant Guid field is empty.	400
ERR_07	Failure to process request	400
ERR_09	The scoach file associated with the reference does not exist.	404
ERR_13	The amount must be less than or equal to that initially recorded	409
ERR_19	Failure to process request	500
ERR_23	The field type is not compatible with the one passed in parameter	400

Service Cancel

Error code	Error label	HTTP CODE
ERR_05	Mandatory URL Reference field not filled in	400
ERR_06	The mandatory Merchant Guid field is empty.	400
ERR_07	Failure to process request	500
ERR_09	The scoach file associated with the reference does not exist.	404
ERR_13	The amount must be less than or equal to that initially recorded	409
ERR_15	File status does not allow cancellation request to be processed	409
ERR_17	File status does not allow cancellation request to be processed	409
ERR_18	The service is not available.	503
ERR_18	Problem when calling simulation service	503
ERR_19	Failed to process request.	500
ERR_20	Payment is in a state that does not allow cancellation	409
ERR_23	The field type is not compatible with the one passed in parameter	400

Service Get_status

Error code	Error label	HTTP CODE
ERR_05	Mandatory URL Reference field not filled in	400
ERR_06	Mandatory field `merchant_guid` is empty	400
ERR_07	Failure to process request.	500
ERR_09	The scoach file associated with the reference does not exist.	404

API marketing

Error code	Error label	Root cause	HTTP CODE
700	It is not possible to produce a simulation from the given elements.	Invalid business transaction code	400