Error reference

All Integration API errors follow RFC 9457 Problem Details (application/problem+json). A single schema covers every failure mode. Auth, validation, concurrency, server errors.

Problem shape

{
  "type": "https://developers.novatrade24.com/problems/unprocessable-entity",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "The request body is not acceptable. See errors for the fields concerned.",
  "instance": "/v1/partners/xxx/buyers",
  "traceId": "req_a1b2c3d4",
  "errors": [
    {
      "field": "vatNumber",
      "message": "must match pattern ^[A-Z]{2}[0-9A-Z]+$"
    }
  ]
}

Field	Type	Notes
`type`	URI string	`https://developers.novatrade24.com/problems/` + `title`, lower-cased with spaces replaced by hyphens. It identifies the status, not a narrower category.
`title`	string	The HTTP reason phrase for `status`. Safe to display.
`status`	integer	HTTP status code, duplicated for convenience.
`detail`	string	Human-readable specifics of this particular occurrence.
`instance`	string	Request path.
`traceId`	string	Correlation id: the `X-Request-Id` you sent, echoed back — the API mints none, so the member is absent when you sent no such header. Send one on every request, and include it in support requests.
`errors[]`	array	Validation failures only: per-field breakdown. Absent on every other problem, including the other `422`.

type and title identify the status, not the reason. They are derived from one another — title is the HTTP reason phrase, type is that phrase slugged onto the problems base URI — so every 409 on this API is …/problems/conflict with the title Conflict, whatever caused it. Branch on status for how to react, and read detail to tell same-status refusals apart: a stale If-Match, an externalOrderId already taken and a duplicate request still in flight are all 409, and only detail says which. detail is prose meant for a human reading a log, so match on it for diagnostics, never as a control-flow key.

Status-code catalog

Status	`title`	`type` URI	What `detail` distinguishes
`400`	`Bad Request`	`…/problems/bad-request`	Unreadable body, missing or oversized `Idempotency-Key`, a lookup given neither or both keys
`401`	`Unauthorized`	`…/problems/unauthorized`	No bearer token, a token that names no API client, a deactivated client
`403`	`Forbidden`	`…/problems/forbidden`	Not authorized to act for the partner in the path, or the token lacks the capability
`404`	`Not Found`	`…/problems/not-found`	No such resource for this caller — a resource belonging to another partner answers `404`, never `403`
`409`	`Conflict`	`…/problems/conflict`	Stale `If-Match`, `externalOrderId` already taken with different details, a duplicate request still in flight, an order split across shipments, a state that cannot accept the write, a buyer or partner that is inactive on Novatrade24
`413`	`Payload Too Large`	`…/problems/payload-too-large`	Nothing — a streamed body sent without `Content-Length` ran past the request-size cap
`422`	`Unprocessable Entity`	`…/problems/unprocessable-entity`	Body failed validation (carries `errors[]`), or an `Idempotency-Key` reused for a different request (no `errors[]`)
`428`	`Precondition Required`	`…/problems/precondition-required`	A write on a versioned resource sent no `If-Match`
`500`	`Internal Server Error`	`…/problems/internal-server-error`	Nothing — send `X-Request-Id` so the response carries a `traceId` you can quote to support

The type URI adds nothing status does not already tell you, because it is derived from the status. It is published so the envelope is a conforming RFC 9457 problem document, not as a branch key.

Handling examples

async function call(url: string, init: RequestInit) {
  const res = await fetch(url, init);
  if (res.ok) return res.json();

  // Branch on `status`. `type` is derived from it and carries no extra
  // information; `detail` says which refusal of that status this one is.
  const problem = await res.json();
  switch (res.status) {
    case 409:
      // Several refusals share this status; `detail` says which. A stale
      // `If-Match`, or a concurrent write that committed first ("modified by
      // another request"), is cured by re-reading and retrying; the others are not.
      throw new Conflict(problem);

    case 428:
      // A versioned resource was written without `If-Match`.
      throw new PreconditionRequired(problem);

    case 422:
      // `errors[]` is present for a validation failure and absent for an
      // `Idempotency-Key` reused with a different body.
      throw problem.errors ? new ValidationFailed(problem) : new IdempotencyKeyReused(problem);

    default:
      throw new ApiError(res.status, problem);
  }
}

def call(session, method, url, **kw):
    r = session.request(method, url, **kw)
    if r.ok:
        return r.json()
    # Branch on the status. `type` is a slug of the status' reason phrase, so
    # it never distinguishes two refusals that share a status; `detail` does.
    problem = r.json()
    if r.status_code == 409:
        # Several refusals share this status; `detail` says which. A stale
        # If-Match, or a concurrent write that committed first, is cured by
        # re-reading and retrying; the others are not.
        raise Conflict(problem)
    if r.status_code == 428:
        raise PreconditionRequired(problem)
    if r.status_code == 422:
        raise ValidationFailed(problem) if "errors" in problem else IdempotencyKeyReused(problem)
    raise ApiError(r.status_code, problem)

Validation errors (`422`)

Body includes an errors[] array with per-field detail:

{
  "type": "https://developers.novatrade24.com/problems/unprocessable-entity",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "The request body is not acceptable. See errors for the fields concerned.",
  "instance": "/v1/partners/.../buyers",
  "traceId": "req_a1b2c3d4",
  "errors": [
    {
      "field": "vatNumber",
      "message": "must match pattern ^[A-Z]{2}[0-9A-Z]+$"
    },
    {
      "field": "address.country",
      "message": "must be a 2-letter ISO-3166-1 alpha-2 code"
    }
  ]
}

Show the per-field messages in your UI; root-level detail is a summary.

Concurrency conflicts (`409` on a stale `If-Match`)

The tag is opaque: compare it, never parse it. A write whose If-Match does not name the current tag is refused with 409 — for a buyer, an invoice and a payment that means the whole tag. An order is narrower: it compares only the part of the tag the write itself could change, so an order write can still succeed after a merely projected field has moved:

{
  "type": "https://developers.novatrade24.com/problems/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "If-Match does not name the current version of this order. Re-read it and retry.",
  "instance": "/v1/partners/.../orders/...",
  "traceId": "req_..."
}

The body is an ordinary problem document and carries no copy of the resource. There is no currentResource member, and no member naming the version you sent or the version in force. Re-read the resource, merge your intended change into what that read returned, and retry with the ETag it carried. order in the detail is the resource that refused the write — invoice and payment word it the same way. A buyer says more, because its record is shared with every partner holding its KYC result and any of them can move it:

{
  "type": "https://developers.novatrade24.com/problems/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "If-Match does not name the current version of this buyer. This record is shared with the other partners that hold its KYC result, so it may have been changed by one of them. Re-read the buyer and retry.",
  "instance": "/v1/partners/.../buyers/...",
  "traceId": "req_..."
}

Omitting If-Match on a versioned resource is a different refusal — 428, not 409 — because a client that forgot the header can simply add it, while one holding a stale tag has to re-read first:

{
  "type": "https://developers.novatrade24.com/problems/precondition-required",
  "title": "Precondition Required",
  "status": 428,
  "detail": "If-Match is required. Send the ETag of the order you read.",
  "instance": "/v1/partners/.../orders/...",
  "traceId": "req_..."
}

409 is not reserved for stale tags: the same status and the same Conflict title answer an externalOrderId already taken, a duplicate request still in flight, and an order split across shipments. Read detail before assuming a retry-after-re-read will help. See optimistic concurrency for how tags are issued, what does and does not make one stale, and a retry loop.

Idempotency key reuse (`422`)

If you reuse an Idempotency-Key within the 24-hour window with a different body, NT24 rejects with 422:

{
  "type": "https://developers.novatrade24.com/problems/unprocessable-entity",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "This Idempotency-Key was already used for a different request. Use a new key, or resend the original request unchanged.",
  "instance": "/v1/partners/.../buyers",
  "traceId": "req_..."
}

This shares its status, title and type with a validation failure. The difference in the body is errors[], which a validation failure carries and this does not. A key whose first request is still running is a 409 rather than a 422: "A request with this Idempotency-Key is still being processed. Retry once it has completed." Generate fresh UUIDs for each logically-distinct request.

Rate limiting

Rate limiting is planned and not yet enforced: no endpoint answers 429 today. See Rate limits.

Troubleshooting

403 but /me succeeds

Your token is valid, but the specific partner in the URL path isn’t in your authorized partners list, OR a capability required for the endpoint (e.g. allowMarketplaceLedKyc) is false on your org. Check GET /v1/me.

409 on POST that was supposed to be idempotent

The resource exists already with a different body than what you’re sending. Either re-send the exact original body, or switch to PATCH to update fields explicitly. Safe retries require both the same Idempotency-Key AND the same body.

422 with no errors[] array

Non-validation 422, most commonly idempotency-key reuse with a different body. type and title are the same for both, so the absent errors[] is the signal — read detail to confirm.

Intermittent 500 errors

Capture traceId from the response body and include it when reaching our contact page. We correlate logs by trace id.

Rate limits

Planned; not yet enforced.

Idempotency

Key format, TTL, replay semantics.

Get Started

Core Concepts

Integration Guide

Webhooks

Reference

Security & Compliance

Problem shape

Status-code catalog

Handling examples

Validation errors (`422`)

Concurrency conflicts (`409` on a stale `If-Match`)

Idempotency key reuse (`422`)

Rate limiting

Troubleshooting

Next

Rate limits

Idempotency

​Problem shape

​Status-code catalog

​Handling examples

​Validation errors (422)

​Concurrency conflicts (409 on a stale If-Match)

​Idempotency key reuse (422)

​Rate limiting

​Troubleshooting

​Next

Rate limits

Idempotency

Problem shape

Status-code catalog

Handling examples

Validation errors (`422`)

Concurrency conflicts (`409` on a stale `If-Match`)

Idempotency key reuse (`422`)

Rate limiting

Troubleshooting

Next