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 CodeMeaning
400 - Bad RequestThere was an issue with the request sent, such as a duplicate payload was sent.
401 - UnauthorizedThe API token is missing or invalid.
403 - ForbiddenThe API token doesn’t have permission to perform this action.
404 - Not FoundThe requested entity (e.g. Transaction) could not be found.
422 - Validation FailedThe request data is invalid. Responses contain errors that show what field failed validation and why.
429 - Too Many RequestsYou 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 ErrorAn 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.
PropertyTypeDescription
messagestringShort error descriptions
errorsobject(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