Error Handling

Standard HTTP response status codes are used to indicate the success or failure of a request made to the Procuros API. Status codes in the 2XX range indicate success, codes in the 4XX and 5XX range indicate failure.

HTTP status codes that can be returned by the Procuros API:

HTTP Status Code	Meaning
400 - Bad Request	There was an issue with the request sent, such as a duplicate payload was sent.
401 - Unauthorized	The API token is missing or invalid.
403 - Forbidden	The API token doesn't have permission to perform this action.
404 - Not Found	The requested entity (e.g. Transaction) could not be found.
422 - Validation Failed	The request data is invalid. Responses contain `errors` that show what field failed validation and why.
429 - Too Many Requests	You are calling the API too much. Check if you can use our bulk endpoints, otherwise contact support to get your rate limit increased. (won't happen to >99% of customers)
500, 502, 503, 504 - Server Error	An error occurred on Procuros side (rare cases)

Error Responses

To help you troubleshoot your interactions with the Procuros API, we've included further information within the responses returned from failed requests to the API.

Property	Type	Description
`message`	string	Short error descriptions
`errors`	object	(Only on 422 "Validation Failed" Errors) Map of fields that failed validation including the corresponding validation error

Message

4xx range responses will always include the message property. For example in the case of a 400, the message property will give you the reason why in English.

{
  "message": "Payload already received"
}

Errors

For "Validation Failed" Client Errors (HTTP status code 422), responses include an additional property errors, which list all request fields that failed validation and why.

Example:

{
  "message": "Invalid data provided.",
  "errors": {
    "type": [
      "The selected type is invalid."
    ]
  }
}

Handling an Error

$client = new \GuzzleHttp\Client();
$response = $client->request(...);

$statusCode = $response->getStatusCode();

if ($statusCode < 200 || $statusCode > 299) {
  // handle error
  // you likely want to check for the exact error codes
}

Example

$headers = [
  'Accept' => 'application/json',
  'Authorization' => 'Bearer <your-api-token>',
];
$transaction = [...]; // A transaction payload

$client = new \GuzzleHttp\Client();
$client->request('POST', 'https://api.procuros.io/v2/transactions', [
  'headers' => $headers,
  'json' => $transaction,
]);

$statusCode = $response->getStatusCode();

if ($statusCode < 200 || $statusCode > 299) {
  if ($statusCode === 400) {
    \Sentry\captureMessage('BadPayloadSent', $transaction);
  }

  if ($statusCode === 422) {
    \Sentry\captureMessage('ValidationError', $transaction);
  }

  if ($statusCode === 500) {
    markDocumentForLaterRetry($transaction);
  }

  \Sentry\captureMessage('UnknownApiError', $transaction);
}

markDocumentAsProcessed($statusCode, $transaction);

Error Handling Best Practises

The most common errors are related to missing or misconfigured data. Here is an example on how to handle these with the Report Outgoing Error Request endpoint.

$client = new \GuzzleHttp\Client();
$client->request('POST', 'https://api.procuros.io/v2/errors', [
  'headers' => $headers,
  'json' => [
    'errorReason' => 'Data XYZ could not be found.',
    'errorType' => 'INTERNAL',
    'errorContext' => [
      'meta' => 'value'
    ],
    'transactionIdentifier' => 'bestellung-20231203-001',
    'transactionType' => 'ORDER',
  ],
]);

Best Practise: Missing GTIN

Set errorType to: DATA.
Set the errorReason to: The GTIN/EAN :gtin couldn't be found and set up the gtin variable accordingly