Errors and Status Codes
Errors come from request validation, authorization, resource lookup, gateway checks, and endpoint-specific business rules.
The single most useful habit: read the status code before the message. 403 and 404 look similar in a log but mean opposite things, and only one of them is worth investigating on your side.
Standard error envelope
{
"success": false,
"message": "The title field is required.",
"errors": {
"title": ["The title field is required."]
}
}Unexpected server failures also include a stable machine code and a support-safe reference:
{
"success": false,
"message": "The request could not be completed.",
"error_code": "public_api_request_failed",
"error_reference": "fa711c5c-0704-4c8f-86dc-76719fbdbb02"
}Provide error_reference to SpaceMedia support. Do not send bearer tokens, API credentials, or private provider data.
Common status codes
| Status | Meaning |
|---|---|
400 | Bad request, invalid token state, malformed date range, or business rule failure. |
401 | Missing bearer token, invalid API credentials, or expired token. |
402 | Organization or user quota, or a payment requirement, blocks the action. |
403 | Permission rules or required account access denied the action. The endpoint exists but the current user cannot perform it. |
404 | Resource not found in the authenticated organization. |
409 | The requested state conflicts with current server state, such as repeating a transition or superseding an already replaced configuration. Read the current resource before deciding whether to retry. |
422 | Request validation failed or checkout/top-up input is incomplete. |
429 | The request exceeded a rate limit. Respect Retry-After when it is present and retry with backoff. |
500 | Gateway, storage, or unexpected server error. |
Validation examples
Release create/update requires a square cover image between 3000x3000 and 5000x5000 pixels, at least one Primary Artist, valid title/version metadata, and a valid release format.
Track create/update normalizes ISRC and ISWC values before validation and requires at least one Primary Artist plus at least one Composer credit.
Revenue split create/update requires title, percentage, and one beneficiary reference: beneficiary_id, beneficiary_email, or email. Release and track assignments are optional unless the endpoint-specific request body says otherwise.
Retry guidance
| Failure | Recommended action |
|---|---|
401 token expired | Create a new bearer token and retry once. |
403 permission denied | Check the acting user, member role, and organization add-on access. Do not retry automatically. |
404 not found | Confirm the reference belongs to the authenticated organization. |
409 state conflict | Read the current resource and continue from its canonical state. Do not blindly repeat the write. |
422 validation failed | Fix the field listed in errors before retrying. |
429 rate limited | Wait for Retry-After, then retry with exponential backoff and jitter. |
500 server failure | Record error_code and error_reference, then retry only when the operation is documented as safe. |
| Payment gateway unavailable | Show a user-facing payment error and retry only after checking gateway status. |
| Upload interrupted | Retry the failed upload or chunk with the same local file metadata. |
For operation-level retry safety, see Rate Limits and Retries. Create, checkout, submit, top-up, install, and publish actions should read current state before repeating after a timeout.
Common questions
Is 403 ever worth retrying?
No. It means a capability, permission, or add-on check failed. Retrying produces the same result. Check the credential's capabilities and whether a gating add-on is active.
Why do I get 404 for a reference I can see in the dashboard?
The reference belongs to a different organization than the credential, or it is an internal identifier rather than the public one.
What is 402 telling me?
A quota or payment requirement is blocking the action, not a technical fault.
What should I send to support?
The error_code and error_reference from the response, plus the endpoint, method, timestamp, and public reference. Never send bearer tokens, API secrets, or provider credentials.
Where is the page metadata documented? On Pagination and Filtering, together with search, sorting, and the different envelope the staging DDEX and webhook collections use.
Was this page helpful?