Vorgio

Error reference

All non-2xx responses from /api/v1/* use RFC 7807 application/problem+json:

 1HTTP/1.1 422 Unprocessable Entity
 2Content-Type: application/problem+json
 3
 4{
 5  "type": "https://vorgio.app/problems/validation-failed",
 6  "title": "The given data was invalid.",
 7  "status": 422,
 8  "detail": "The invoice.positions.0.amount_cents field is required when invoice.positions.0.mode is fixed.",
 9  "errors": {
10    "invoice.positions.0.amount_cents": [
11      "The amount_cents field is required when mode is fixed."
12    ]
13  }
14}

The type URI is stable and is what your code should branch on — never the title (which is human-readable and may be translated).

#Common problem types

#validation-failed (422)

Body shape error. Includes an errors object keyed by field path.

What to do: surface to the developer / merchant; never to the end customer (the field paths leak schema). Most validation errors mean your shop sent something Vorgio doesn't accept — fix the request shape.

#idempotency-key-conflict (409)

You re-used an Idempotency-Key with a different request body. Vorgio refuses because the only safe behaviour is to surface the conflict.

What to do: pick a different idempotency key (or scope the existing one to this attempt — append a retry counter, e.g. wc-order-1234-checkout-r2). Don't modify the body and re-send under the same key.

#forbidden (403)

The token doesn't have the ability the endpoint requires. For example, calling POST /v1/checkouts with a token that only has clients:read.

What to do: re-issue the token with the correct abilities. The "Payment-provider integration" preset on the token UI selects the right set.

#unauthenticated (401)

Bearer token is missing, malformed, or expired/revoked.

What to do: check the Authorization header. The format is Bearer {numeric_id}|{plain_secret} — both halves separated by a pipe. Don't send only the secret half.

#too-many-requests (429)

Rate limit exceeded. See Rate limits.

#not-found (404)

The resource doesn't exist in your team. Note that resources in other teams also return 404, not 403 — this is intentional (avoids leaking the existence of other teams' data).

What to do: double-check the client_id / invoice_id. If it should exist, check whether it was soft-deleted or whether the token belongs to the wrong team.

#client-has-retained-invoices (409, on DELETE /v1/clients/{id})

You tried to delete a client that has invoices inside the German 10-year legal-retention window (HGB §257, AO §147). Vorgio refuses by law.

What to do: don't delete; archive in your shop instead.

#invoice-not-editable (422, on PATCH /v1/invoices/{id})

You tried to change a finalised invoice, which GoBD forbids, or to set is_draft: true or a different type on a numbered row. This problem has no errors map, because no field is at fault.

What to do: reverse a finalised invoice via POST /v1/invoices/{id}/cancel. Don't retry the PATCH.

#internal-error (5xx)

Something exploded server-side. The detail may contain an error reference for support.

What to do: retry with exponential back-off; if it persists, send the error reference to Vorgio support. Don't show the internal error message to your end customer.

#Validation-error field paths

For nested request bodies (like /v1/checkouts), error keys use dot-notation:

Path What it means
client.external_id Top-level field on the client block
invoice.positions.0.amount_cents The amount_cents field on the first position
send.cc.2 The third entry in the send.cc array

When surfacing errors back to a developer, render each errors array entry as a bullet list under its field path.

#Suggested error-handling pattern (PHP)

 1try {
 2    $response = $http->post('/api/v1/checkouts', [...]);
 3} catch (RequestException $e) {
 4    $body = json_decode((string) $e->getResponse()->getBody(), true);
 5    $type = $body['type'] ?? '';
 6
 7    match (true) {
 8        str_ends_with($type, 'validation-failed') => $this->reportToDeveloper($body),
 9        str_ends_with($type, 'too-many-requests') => $this->scheduleRetry($body, $e->getResponse()->getHeader('Retry-After')[0] ?? 60),
10        str_ends_with($type, 'idempotency-key-conflict') => $this->logAndAlertEng($body),
11        $e->getCode() >= 500 => $this->retryWithBackoff(),
12        default => throw $e,
13    };
14}