> ## Documentation Index
> Fetch the complete documentation index at: https://docs.procuros.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<CodeGroup>
  ```json json theme={null}
  {
    "message": "Payload already received"
  }
  ```
</CodeGroup>

### 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:

<CodeGroup>
  ```json json theme={null}
  {
    "message": "Invalid data provided.",
    "errors": {
      "type": [
        "The selected type is invalid."
      ]
    }
  }
  ```
</CodeGroup>

### Handling an Error

<CodeGroup>
  ```php php theme={null}
  $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
  }

  ```
</CodeGroup>

### Example

<CodeGroup>
  ```php php theme={null}
  $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);
  ```
</CodeGroup>

### 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](/en/api/v2/outgoing-transactions/report-outgoing-error) endpoint.

<CodeGroup>
  ```php php theme={null}
  $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', ], ]);
  ```
</CodeGroup>

#### 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