Troubleshooting
Use this page when an integration works in a small test but fails during a real customer workflow. Start with the symptom, confirm the likely cause, then use the recovery action before opening a support request.
Fast triage
| Symptom | Likely cause | Recovery |
|---|---|---|
| Token request fails | API credentials are wrong, inactive, or copied from the wrong organization. | Regenerate credentials from the correct organization admin account and exchange them again. |
Protected endpoint returns 401 | Bearer token is missing, expired, or not sent in the Authorization header. | Exchange credentials for a fresh token and retry the protected request once. |
Endpoint returns 403 | The credential owner or acted-for user lacks permission, or the required add-on is not active. | Check user role, member permissions, and add-on access. Do not retry automatically. |
Endpoint returns 404 for a known record | The public reference belongs to a different organization or the wrong reference field was used. | Fetch the record list in the authenticated organization and use the returned public reference. |
| Create request appears to duplicate data | Client retried a write after timeout without checking current state. | Search or fetch the matching record before creating another one. |
| Release cannot submit | Metadata, rights, artwork, tracks, or destinations are incomplete. | Run readiness checks, fix every blocking issue, then submit once. |
| Release status does not change immediately | Review and delivery are asynchronous workflows. | Poll the documented review or delivery endpoint with a bounded interval. |
| Checkout completes but access is not updated | Checkout verification was not called or payment is still pending. | Verify the checkout with checkout_id and read the related billing or add-on state. |
| Upload succeeds but track creation fails | Client did not pass the returned audio_file_id, or the release reference is wrong. | Use the audio_file_id from the successful upload response and the current release_id. |
| SDK code compiles but fails at runtime | Generated client renamed public fields or hides response metadata. | Keep public field names and expose meta, message, errors, and public references. |
Authentication checks
- Confirm the base URL is
https://enterprise.spacemedia.uk. - Exchange API key and secret with
POST /api/v1/token. - Store the returned bearer token securely.
- Send the token in the
Authorizationheader on protected calls. - Refresh before expiry instead of repeatedly retrying failed protected calls.
Never send the API secret after token exchange.
Permission and add-on checks
If a call returns 403, check:
- The API product is active for the organization.
- The authenticated user has access to the workflow.
- The acted-for user belongs to the same organization.
- The endpoint supports acted-for user context.
- The required add-on is active.
- The operation is not admin-only when the acting user is a catalog user.
Do not work around 403 by adding organization selectors or internal references to the request.
Catalog delivery checks
Before release submission:
- Confirm artists exist and use public
artist_idvalues. - Confirm release metadata is complete.
- Confirm cover art passes validation.
- Confirm each uploaded track has an
audio_file_id. - Confirm each created track has a stable
track_id. - Confirm track order is final.
- Confirm rights, territories, and distribution channels are set.
- Run readiness checks.
- Submit only after all blocking issues are fixed.
If submission times out, fetch the release and review state before retrying.
Metadata checks
Common metadata causes of review or delivery problems:
| Problem | Fix |
|---|---|
| Featured artist text is only in the title. | Send featured artists as structured artist roles. |
| Remix or clean version is duplicated in title and version fields. | Keep title and version data separate. |
| Cover art includes URLs, pricing, or promo text. | Upload clean square artwork that matches the release. |
| ISRC is reused for a different recording. | Use one ISRC per recording, edit, remix, or clean version. |
| Territories do not match rights. | Send only territories where the customer has delivery rights. |
| Explicit content is not marked. | Set explicit flags accurately at release and track level where available. |
Use Metadata Style Guide before resubmitting.
Payment and checkout checks
For checkout workflows:
- Store
checkout_id. - Treat embedded checkout data as short-lived.
- Verify checkout state after the user returns.
- Do not create another checkout after a timeout until the first checkout state is known.
- Show a clear recovery action for expired, cancelled, or failed checkouts.
Polling checks
Polling should stop when it has enough information.
| Workflow | Stop polling when |
|---|---|
| Readiness | No blocking issue remains or the operator leaves the edit flow. |
| Review | The release has a terminal review state or the integration switches to background sync. |
| Delivery | The release is delivered, rejected, failed, or moved into manual handling. |
| Checkout | The checkout is completed, failed, cancelled, or expired. |
If polling receives 429, slow down immediately and follow Rate Limits and Retries.
Support packet
Send support only the data needed to investigate:
- Endpoint and HTTP method.
- Public reference such as
release_id,track_id,checkout_id,user_id, orsmartlink_id. - Timestamp and timezone.
- Status code.
- Sanitized response body.
- Client or SDK version.
- Retry count and last retry time.
- Current resource state after the failure.
Do not send API secrets, bearer tokens, webhook secrets, private keys, raw customer credentials, or provider payment references.
Related pages
Was this page helpful?
Go-Live Checklist
Production readiness checklist for Enterprise API customers before sending live catalog, payment, user, or branding automation.
SDK Generation
How official and generated SDKs should use the Enterprise API OpenAPI contract, public reference names, pagination, retries, and publishing checks.