UMW API Error Codes, HTTP Status Codes, and Responses

Every error returned by the UMW API follows a consistent JSON structure, regardless of the endpoint or the nature of the failure. This predictable format means your integration can use a single error-handling routine to parse, log, and surface actionable information for every failure case — from simple validation errors to transient platform issues.

Error Response Object

When the API returns a non-2xx status code, the response body will always contain a top-level error object with the following shape:

{
  "error": {
    "code": "invalid_release_date",
    "message": "release_date must be at least 7 days in the future.",
    "request_id": "req_01HXK9VTPR4BNMQ7YZW2D3EF8",
    "details": [
      { "field": "release_date", "issue": "must be at least 7 days in the future" }
    ]
  }
}

string

required

A stable, machine-readable identifier for the error type. Use this value in your application logic to branch on specific error conditions. Error codes do not change across patch releases.

string

required

A human-readable description of the error intended for developers. Messages may change over time and should not be parsed programmatically — use code for logic branching.

string

required

A unique identifier for the API request that produced the error. Every request receives a request_id regardless of outcome. Always include this value when contacting UMW support — it allows the support team to look up the exact request and trace the failure for you.

array of objects

An array of granular validation issues. Each entry identifies the specific field that failed and an issue string describing the constraint that was violated. This array is most commonly populated on 422 Unprocessable Entity responses but may appear on 400 responses as well.

string

The dot-notation path of the request field that caused the validation failure (e.g., release_date, tracks[0].isrc).

string

A plain-language description of the validation constraint that was not satisfied.

HTTP Status Codes

The UMW API uses standard HTTP status codes to indicate the outcome of every request. The table below describes each code your integration may encounter.

Status Code	Name	Description
`400`	Bad Request	The request was malformed or contained invalid field values that could not be interpreted. Check the `details` array for specifics.
`401`	Unauthorized	No authentication credential was provided, or the credential is invalid or expired. Verify your `Authorization` header and API key status.
`403`	Forbidden	Your credential is valid, but the authenticated organization lacks the permissions required for this action. Contact your UMW account manager to review your access scope.
`404`	Not Found	The requested resource does not exist, has been deleted, or is not accessible to your organization. Confirm the resource ID and your organization’s ownership.
`409`	Conflict	The request conflicts with the current state of the resource. Common examples include attempting to re-submit a release that is already under review.
`422`	Unprocessable Entity	The request was well-formed but failed business-logic validation. Inspect the `details` array to identify and correct each field-level issue.
`429`	Too Many Requests	Your organization has exceeded its rate limit for the current window. Check the `Retry-After` response header for the number of seconds to wait before retrying.
`500`	Internal Server Error	An unexpected error occurred on the UMW platform. These errors are automatically logged and monitored. Retry the request using exponential backoff; if the issue persists, contact support with the `request_id`.

Common Error Codes

The following error codes appear frequently across UMW API endpoints. Each code value is stable and safe to use in programmatic error handling.

missing_required_field

HTTP Status: 422 Unprocessable EntityA required field was absent from the request body. The details array will identify every missing field in a single response, so you can correct all omissions before retrying.

{
  "error": {
    "code": "missing_required_field",
    "message": "One or more required fields are missing.",
    "request_id": "req_01HXK9VTPR4BNMQ7YZW2D3EF8",
    "details": [
      { "field": "title", "issue": "field is required" },
      { "field": "label_id", "issue": "field is required" }
    ]
  }
}

invalid_isrc_format

HTTP Status: 422 Unprocessable EntityThe ISRC value provided does not conform to the ISO 3901 format (CC-XXX-YY-NNNNN). Verify that the country code, registrant code, year, and designation are all present and correctly formatted.

{
  "error": {
    "code": "invalid_isrc_format",
    "message": "The ISRC 'US-ABC-24' does not conform to ISO 3901.",
    "request_id": "req_01HYM3VTPR4BNMQ7YZW2D3EF9",
    "details": [
      { "field": "tracks[0].isrc", "issue": "must match pattern CC-XXX-YY-NNNNN" }
    ]
  }
}

duplicate_submission

HTTP Status: 409 ConflictA release or delivery with an identical fingerprint (same UPC, label, and release date) has already been submitted by your organization. If you intended to update an existing release, use the PATCH /v1/releases/{release_id} endpoint rather than creating a new record.

{
  "error": {
    "code": "duplicate_submission",
    "message": "A release with UPC 00602507455620 was already submitted on 2024-05-10.",
    "request_id": "req_01HZP9VTPR4BNMQ7YZW2D3EG0",
    "details": [
      { "field": "upc", "issue": "duplicate UPC for this label and release date" }
    ]
  }
}

asset_not_ready

HTTP Status: 409 ConflictOne or more audio or artwork assets referenced in the request have not completed processing. Assets must reach ready status before the associated release or delivery can be submitted. Poll GET /v1/assets/{asset_id} until the status transitions, or listen for the asset.ready webhook event.

{
  "error": {
    "code": "asset_not_ready",
    "message": "Asset ast_01HXK9VTPR4BNM is still processing and cannot be used in a submission.",
    "request_id": "req_01JAP9VTPR4BNMQ7YZW2D3EG1",
    "details": [
      { "field": "tracks[2].asset_id", "issue": "asset status is 'processing', expected 'ready'" }
    ]
  }
}

territory_not_supported

HTTP Status: 422 Unprocessable EntityA territory code provided in the delivery or release request is not supported by the UMW distribution network, or your organization is not licensed to distribute to that territory. Refer to GET /v1/stores/territories for the full list of supported territory codes available to your account.

{
  "error": {
    "code": "territory_not_supported",
    "message": "Territory 'XX' is not a supported distribution market.",
    "request_id": "req_01KBQ9VTPR4BNMQ7YZW2D3EG2",
    "details": [
      { "field": "territories[4]", "issue": "'XX' is not a valid ISO 3166-1 alpha-2 territory code" }
    ]
  }
}

rate_limit_exceeded

HTTP Status: 429 Too Many RequestsYour organization has sent more requests than your tier permits within the current rate-limit window. Inspect the Retry-After response header to determine how many seconds to wait before the next request. See the Rate Limits reference for details on tier limits and implementing exponential backoff.

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "You have exceeded the request limit for your plan. Please wait before retrying.",
    "request_id": "req_01LCR9VTPR4BNMQ7YZW2D3EG3",
    "details": []
  }
}

Always capture and log the request_id from every API response — not just errors. When you contact UMW Developer Support, providing the request_id immediately allows the support team to locate the exact request and diagnose the failure without requiring you to reproduce the issue.

Get Started

Platform Guides

Platform Reference

UMW API Error Codes, HTTP Status Codes, and Responses

Error Response Object

HTTP Status Codes

Common Error Codes

​Error Response Object

​HTTP Status Codes

​Common Error Codes

Error Response Object

HTTP Status Codes

Common Error Codes