Reference

Errors

Every status and machine-readable error code the APIs return.

Every error body has the same shape. Match on code, not on the message text. We may improve a message at any time. A code only changes under a new version path.

json

{
  "error": "This Idempotency-Key was already used with a different request body.",
  "code": "IDEMPOTENCY_MISMATCH"
}

Every response, success or error, carries an x-request-id header. Quote it when you contact support. It is how we find your exact request in our logs.

Error codes#

`code`	Status	Meaning	What to do
`AUTH_MISSING`	401	No `Authorization: Bearer <token>` header.	Send the header.
`AUTH_INVALID`	401	The key is invalid, expired or revoked.	Check the key. Create a new one if needed.
`API_KEY_KIND_INVALID`	403	A shared internal key was used where a per-client `trk_` key is required.	Use a per-client key.
`SCOPE_MISSING`	403	The key does not carry the scope this endpoint needs.	Ask us to grant the scope.
`CLIENT_MISMATCH`	403	The `x-client-id` header does not match the key's client.	Remove the header, or send the right one.
`CLIENT_ID_MISSING`	400	The endpoint needs a client id and none resolved.	Send a per-client key.
`VALIDATION_ERROR`	400	The request body failed validation.	Read `error`. Correct the request. Do not retry unchanged.
`IDEMPOTENCY_IN_FLIGHT`	409	A request with this `Idempotency-Key` is still running.	Wait, then retry the same request.
`IDEMPOTENCY_MISMATCH`	422	This `Idempotency-Key` already ran with a different body.	Use a new key for a new body.
`RATE_LIMITED`	429	You passed the rate limit for this key.	Wait for `Retry-After` seconds, then retry.
`INTERNAL_ERROR`	500	We failed.	Retry with backoff. Quote the `x-request-id`.

The Partner Metadata API adds three codes of its own: INVALID_IDENTIFIER (400), ASSET_NOT_FOUND (404) and SOURCE_UNAVAILABLE (503).

What returns a 400#

The Catalogue Ingest request schema is strict. These all return 400 VALIDATION_ERROR:

An unknown or misspelled field. We reject it. We do not ignore it.
A duplicate client_work_ref inside one batch.
A publisher-to-writer link that does not resolve.
A share outside the 0 to 100 range.
A body client_id that does not match your key.
A client_artist_ref that conflicts with existing catalogue state.
A blocking validation issue, when you sent enforcement: "strict". Nothing is stored. The message names how many works carried one, and mode: "validate" shows you the same issues without storing.

A catalog_id we cannot find for your account returns 404 NOT_FOUND.

A 400 is a problem with your request. Correct it. Retrying the same body will fail the same way.

Which errors to retry#

Status	Retry?
400, 401, 403, 404, 422	No. Correct the request first.
409	Yes, after a short wait.
429	Yes, after `Retry-After` seconds.
500, 502, 503, 504	Yes, with exponential backoff.

Rate limits and retries has a worked retry loop.

Errors are not gaps#

A 2xx response can still report problems with your data. Missing fields arrive in gaps, and data that is present but wrong arrives in validation. Neither blocks the write, and neither is an HTTP error. See Validation and gaps.