Error reference

All Integration API errors follow RFC 7807 Problem Details (application/problem+json). A single schema covers every failure mode — auth, validation, concurrency, rate-limiting, server errors.

Problem shape

{
  "type": "https://api.novatrade24.com/problems/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "Field 'vatNumber' must match pattern ^[A-Z]{2}[0-9A-Z]+$",
  "instance": "/v1/partners/xxx/buyers",
  "traceId": "req_a1b2c3d4",
  "errors": [
    {
      "field": "vatNumber",
      "message": "must match pattern ^[A-Z]{2}[0-9A-Z]+$",
      "rejectedValue": "invalid"
    }
  ]
}

Field	Type	Notes
`type`	URI string	Stable identifier for the error category. Keyed on this, not on `status` or `title`.
`title`	string	Human-readable summary. 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. Include in support requests.
`errors[]`	array	Validation-error only — per-field breakdown.

Always key on type, not on status or title. We may add new problem types over time; we will not change existing ones without a version bump.

Status-code catalog

Status	Meaning	Typical `type` URIs
`400`	Malformed request	`…/problems/malformed-request`
`401`	Missing or invalid token	`…/problems/unauthorized`
`403`	Authenticated but not authorized (partner scope, capability, DPA)	`…/problems/forbidden`, `…/problems/capability-required`, `…/problems/dpa-not-accepted`
`404`	Resource not found	`…/problems/not-found`
`409`	State conflict (If-Match mismatch, natural-key collision, milestone already set)	`…/problems/version-mismatch`, `…/problems/resource-exists-different-body`, `…/problems/milestone-already-set`
`422`	Validation failed or idempotency key reused with different body	`…/problems/validation-error`, `…/problems/idempotency-key-reused`
`429`	Rate limit exceeded	`…/problems/rate-limited`
`500`	Unexpected server error	`…/problems/internal-error`

Handling examples

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

  const problem = await res.json();
  switch (problem.type) {
    case 'https://api.novatrade24.com/problems/version-mismatch':
      // Refetch and retry with new ETag.
      throw new VersionMismatch(problem);

    case 'https://api.novatrade24.com/problems/rate-limited':
      const retryAfter = parseInt(res.headers.get('Retry-After') ?? '1', 10);
      await new Promise((r) => setTimeout(r, retryAfter * 1000));
      return call(url, init);

    case 'https://api.novatrade24.com/problems/dpa-not-accepted':
      alertOps('Novatrade24 DPA needs re-acceptance', problem);
      throw new DpaStale(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()
    problem = r.json()
    t = problem.get("type", "")
    if t.endswith("/rate-limited"):
        time.sleep(int(r.headers.get("Retry-After", "1")))
        return call(session, method, url, **kw)
    if t.endswith("/version-mismatch"):
        raise VersionMismatch(problem)
    if t.endswith("/dpa-not-accepted"):
        raise DpaStale(problem)
    raise ApiError(r.status_code, problem)

Validation errors (`422`)

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

{
  "type": "https://api.novatrade24.com/problems/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "Request body failed validation. See errors[].",
  "instance": "/v1/partners/.../buyers",
  "traceId": "req_a1b2c3d4",
  "errors": [
    {
      "field": "vatNumber",
      "message": "must match pattern ^[A-Z]{2}[0-9A-Z]+$",
      "rejectedValue": "invalid"
    },
    {
      "field": "address.country",
      "message": "must be a 2-letter ISO-3166-1 alpha-2 code",
      "rejectedValue": "ger"
    }
  ]
}

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

Concurrency conflicts (`409` with version mismatch)

When a PATCH carries an If-Match header that doesn’t match the current entity version, NT24 returns 409 with the full current resource body — you don’t need a separate GET to reconcile.

{
  "type": "https://api.novatrade24.com/problems/version-mismatch",
  "title": "Version Mismatch",
  "status": 409,
  "detail": "If-Match version 3 does not match current version 5.",
  "instance": "/v1/partners/.../orders/...",
  "traceId": "req_...",
  "currentResource": {
    "uuid": "...",
    "version": 5,
    "...": "..."
  }
}

Merge locally and retry with the new ETag.

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://api.novatrade24.com/problems/idempotency-key-reused",
  "title": "Idempotency Key Reused With Different Body",
  "status": 422,
  "detail": "Key 'abc-123' was first used for a different request. Use a new key.",
  "instance": "/v1/partners/.../buyers",
  "traceId": "req_..."
}

Generate fresh UUIDs for each logically-distinct request.

Rate limiting (`429`)

{
  "type": "https://api.novatrade24.com/problems/rate-limited",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "60 requests per minute for write category exceeded.",
  "instance": "/v1/partners/.../orders",
  "traceId": "req_..."
}

Response headers carry the budget state — honor Retry-After:

Retry-After: 37
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1729684260

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 different body. Check type.

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

Tier breakdowns and burst behavior.

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` with version mismatch)

Idempotency key reuse (`422`)

Rate limiting (`429`)

Troubleshooting

Next

Rate limits

Idempotency

​Problem shape

​Status-code catalog

​Handling examples

​Validation errors (422)

​Concurrency conflicts (409 with version mismatch)

​Idempotency key reuse (422)

​Rate limiting (429)

​Troubleshooting

​Next

Rate limits

Idempotency

Problem shape

Status-code catalog

Handling examples

Validation errors (`422`)

Concurrency conflicts (`409` with version mismatch)

Idempotency key reuse (`422`)

Rate limiting (`429`)

Troubleshooting

Next