API

Error messages

It is inevitable that an error message will appear sooner or later, even when using the RamBase API. Luckily, all error message follows the same format, including the following information:

  • HTTP status code
    The HTTP status code used for the HTTP response. Read more about the different HTTP status codes below.
  • HTTP status description
    A short description of the HTTP status code
  • Message
    A detailed message describing the error.
  • Translated message
    The message translated to the language specified in the $lang query parameter.
  • Error message
    All error messages in RamBase is represented as an object. This means that all error message in RamBase have a unique identifier and even API resources representing it.
  • Parameters
    Some error messages have one or more parameters in the message. These are listed here. Note that Message and TranslatedMessage already have the parameters replaced by the parameter values.
  • Inner errors
    In some cases an error might have inner errors. The inner error follows the same format as the error itself, but without HTTP status code and HTTP status description.

You can find a list of most error message that can occur when requesting a specific API resource in the API documentation. Use this list to learn and prepare for different errors that might occur.

HTTP status codes

The errors returned from the RamBase API is limited to four different HTTP status codes. These status code makes a good indication of what type of error this is and who is responsible for fixing the error:

  • 400 - Bad request
    Something is wrong with the request. It might be a syntax error in the request body, a wrong field uses in the filter etc. Make changes to the request before sending it again.
  • 403 - Forbidden
    Either the API client is missing permission to the API resource or the user performing the request is missing the right duties/roles to perform the request.
  • 404 - Not found
    Either the API resource does not exist or some of the provided input references something that does not exist.
  • 500 - Internal server error
    Something is wrong on our side. Please contact us to let us know what you did and what went wrong.

Some examples

This is an error received when requesting the non-existing API resource POST /sales/rabbits. Notice the two parameters for verb and uri:

1
{
2
  'hTTPStatusCode': '404',
3
  'hTTPStatusDescription': 'NotFound',
4
  'message': 'Resource not found: POST /sales/rabbits',
5
  'translatedMessage': 'Resource not found: POST /sales/rabbits',
6
  'errorMessage': {
7
    'errorMessageId': 80026,
8
    'errorMessageLink': 'https://api.rambase.net/system/error-messages/80026'
9
  },
10
  'parameters': [
11
    {
12
      'index': 0,
13
      'value': 'POST'
14
    },
15
    {
16
      'index': 1,
17
      'value': '/sales/rabbits'
18
    }
19
  ],
20
  'innerErrors': []
21
}

This is an error received when trying to update some fields of a sales order. Notice the translated message because of adding $lang=nob to the query parameters of the request:

1
{
2
  'hTTPStatusCode': '400',
3
  'hTTPStatusDescription': 'BadRequest',
4
  'message': 'You can not change a processed (status 9) sales order',
5
  'translatedMessage': 'Du kan ikke endre en ferdigbehandlet (status 9) salgsordre',
6
  'errorMessage': {
7
    'errorMessageId': 101766,
8
    'errorMessageLink': 'https://api.rambase.net/system/error-messages/101766'
9
  },
10
  'parameters': [],
11
  'innerErrors': []
12
}