Skip to content

Error codes

Error response rules for the KiTbetter Partner API.

This list may grow

The status codes and error codes below reflect the currently published spec. The list expands as endpoints are added or changed.

HTTP status codes

Status code Meaning Common causes and what to do
400 Bad Request Malformed request Missing required parameter or invalid format. Check the request body and parameters against the spec
401 Unauthorized Authentication failed Missing, mistyped, or revoked X-API-Key. See Authenticate requests
403 Forbidden Not permitted The key is valid but has no access to the resource. Contact us about your partner scope
404 Not Found Resource not found Wrong path, or a resource ID that does not exist
409 Conflict Duplicate ingest The same releaseId has already been ingested. Resending does not update it — check the existing ingest in error.details
422 Unprocessable Entity Cannot be processed XML download or parse failure, and similar. No ingest is created — fix the cause and resend
429 Too Many Requests Rate limit exceeded Too many calls. Check the Retry-After header, then retry — see Rate limits
500 Internal Server Error Server error Check server status and retry. If it persists, contact us with the requestId

Error response format

Every error response returns a JSON body in the following format.

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "The request parameters are invalid.",
    "requestId": "req_01HZX..."
  }
}
Field Description
error.code Machine-readable error code string. See the error code list below
error.message Human-readable description. The wording may change, so branch on code instead
error.requestId Request tracing identifier
error.details Optional error-specific data. DUPLICATE_RELEASE includes the existing ingest (ingestId, status, receivedAt)

Error code list

Code HTTP Meaning What to do
INVALID_PARAMETER 400 Missing required field, invalid format, or an expiry time in the past Compare the request body against the spec
INVALID_API_KEY 401 Key missing, invalid, or revoked Check the header name (X-API-Key) and the key value. Reissue if needed
PROVIDER_INACTIVE 403 Partner has been deactivated Contact your partner manager
FORBIDDEN 403 The key is not authorized to call this API Contact us about your partner scope
DUPLICATE_RELEASE 409 The same releaseId was already ingested — resending does not update it Use the existing ingest in error.details; contact your partner manager if changes are needed
XML_FETCH_FAILED 422 Could not download xmlUrl (unreachable, expired, or 10-second timeout) Check the URL's expiry, then resend
XML_PARSE_FAILED 422 ERN parse failure or missing required element Validate the XML against DDEX ERN 3.8.2, then resend
ARTIST_UNRESOLVED 422 Artist could not be resolved Contact your partner manager, then resend
INGEST_NOT_FOUND 404 Ingest not found — it does not exist, or belongs to another partner Verify the ingestId matches the one returned when the ingest was created
RATE_LIMITED 429 Rate limit exceeded Wait for Retry-After, then retry — see Rate limits
INTERNAL_ERROR 500 Server error Retry shortly. If it persists, contact us with the requestId

422 errors mean no ingest was created, so you can resend once the cause is fixed. Only 409 cannot be resent.

Ingest failure reason codes

These are the values returned in error.code when an ingest's status is failed. They are a separate system from the HTTP error codes above — the ingest was already created and failed later, during resource file loading.

Code Meaning What to do
RESOURCE_FETCH_FAILED Could not download a resource file (audio, video, image) — URL expired or unreachable Check the expiry of the file URLs inside the XML and ask your partner manager to resend them
RESOURCE_HASH_MISMATCH The downloaded file's hash does not match the <HashSum> value in the XML Compare the source file against the value declared in the XML
INTERNAL_ERROR Internal KiTbetter error Contact us with the ingestId

Do not resend a failed ingest

Resending the same releaseId returns 409. A failed ingest can be resumed by KiTbetter operations, so contact us with the ingestId instead.

New codes may be added, so treat unknown codes as generic failures in your implementation.

Include the requestId when you contact us

With a requestId we can trace the server logs for that exact request. When reporting an error, send the requestId along with the time it occurred and the endpoint to our support channels.