NinjaBuy

Errors follow the RFC 9457 problem JSON contract, with media type application/problem+json.

{
  "type": "https://www.ninjabuy.com/api/v1/problems/bad-body",
  "title": "Invalid request",
  "status": 400,
  "detail": "The request did not match the expected shape.",
  "request_id": "REQUEST_ID",
  "errors": [{"pointer": "/links", "detail": "Validation detail"}]
}

type is the stable problem identifier; title and detail describe it. status matches the HTTP status. Optional errors entries contain a JSON Pointer and validation detail; an empty pointer means the whole body. Quote request_id (also in X-Request-Id) when reporting a problem.

All types below start with https://www.ninjabuy.com/api/v1/problems/.

Type suffix	HTTP	Meaning / action
`bad-json`	400	Body is not valid JSON. Fix its syntax.
`bad-body`	400	Body, query parameters or cursor fail validation. Read `errors`.
`bad-idempotency-key`	400	Use 1 to 255 printable ASCII characters for `Idempotency-Key`.
`unauthorized`	401	Supply a valid bearer token; `WWW-Authenticate` provides discovery.
`not-found`	404	Resource is unavailable, unknown or not owned by this account.
`method-not-allowed`	405	Use the method in `Allow`.
`idempotency-key-in-progress`	409	The first request with this key is running. Wait for `Retry-After`.
`upload-too-large`	413	Uploaded bytes exceed the declared size or 20 MiB limit.
`unsupported-media-type`	415	Send `Content-Type: application/json`.
`idempotency-key-reused`	422	This key was used with another request. Use a new key.
`invalid-workbook`	422	Upload is not a readable XLSX/CSV within the limits. Read `errors`.
`upload-expired`	422	Upload reservation expired. Upload the file again.
`rate-limited`	429	Wait the `Retry-After` seconds before retrying.
`search-rate-limited`	429	The keyword-search window is full. Wait for `Retry-After`.
`service-unavailable`	503	Retry shortly; respect `Retry-After` when present.
`internal-error`	500	Retry later; retain the request id if it persists.

A successful request can still contain per-input failures. Handle link statuses separately from HTTP errors. Use Idempotency-Key to replay a create request; without a key, retrying a batch submission creates another job.