DOCUMENTATION
Errors & retries
HTTP statuses, error codes and safe retries.
HTTP status codes#
| HTTP | Client action |
|---|---|
| 400 | Correct schema-invalid parameters or body. |
| 401 | Check credential type, expiry and revocation. The API does not redirect to an HTML login page. |
| 403 | Check scopes, consent, role and ownership. |
| 404 | The resource is missing or inaccessible to this user. |
| 409 | Resolve the conflict/offset mismatch. Never blindly retry a write. |
| 410 | The upload session or download ticket expired. Never replay the old secret; establish the previous operation outcome first. |
| 413 | The request body or file chunk exceeds its limit. Reduce the size before retrying. |
| 415 | Unsupported Content-Type/encoding: chunks require raw application/octet-stream without compression. |
| 422 | Domain validation rejected content where this status is defined. Correct the data/archive. |
| 429 | Honor Retry-After; quota is shared. |
| 503 | For reads, use bounded retries with backoff. For writes, check the previous operation outcome first. |
Captured error responses#
HTTP responses captured in a local test environment. Request IDs vary. OAuth returns JSON without a wrapper; other operations use the API envelope.
401 · invalid credential
GET /public/v1/mods
HTTP response
HTTP/1.1 401
x-request-id: 503ef036-d2a8-4b0c-a5e9-4e8855bb68d5
cache-control: no-store
content-type: application/json; charset=utf-8
{
"success": false,
"error": {
"code": "API_BEARER_REQUIRED",
"message": "Use a developer key or a delegated user token"
},
"meta": {
"requestId": "503ef036-d2a8-4b0c-a5e9-4e8855bb68d5"
}
}400 · invalid parameter
GET /public/v1/mods?limit=bad
HTTP response
HTTP/1.1 400
ratelimit-limit: 60
ratelimit-remaining: 57
ratelimit-reset: 60
x-request-id: 3a4f6daf-08df-4f43-903b-22e17ff4b485
cache-control: no-store
x-quota-limit: 10000
x-quota-remaining: 9996
x-quota-reset: 1797148615
content-type: application/json; charset=utf-8
{
"success": false,
"error": {
"code": "INVALID_ID",
"message": "Request rejected"
},
"meta": {
"requestId": "3a4f6daf-08df-4f43-903b-22e17ff4b485"
}
}403 · insufficient permissions
POST /public/v1/upload-sessions
HTTP response
HTTP/1.1 403
x-request-id: 7a4b2f07-a816-42ca-8b8f-33b1290b6988
cache-control: no-store
content-type: application/json; charset=utf-8
{
"success": false,
"error": {
"code": "API_SCOPE_REQUIRED",
"message": "Credential lacks the required public scope"
},
"meta": {
"requestId": "7a4b2f07-a816-42ca-8b8f-33b1290b6988"
}
}404 · resource not found
GET /public/v1/mods/2147483647
HTTP response
HTTP/1.1 404
ratelimit-limit: 60
ratelimit-remaining: 56
ratelimit-reset: 60
x-request-id: 51456789-06cd-426b-8c4b-424e25becc03
cache-control: no-store
x-quota-limit: 10000
x-quota-remaining: 9996
x-quota-reset: 1797148615
content-type: application/json; charset=utf-8
{
"success": false,
"error": {
"code": "MOD_NOT_FOUND",
"message": "Request rejected"
},
"meta": {
"requestId": "51456789-06cd-426b-8c4b-424e25becc03"
}
}OAuth · code exchange error
POST /public/v1/oauth/token
HTTP response
HTTP/1.1 400
x-request-id: f1e15906-6833-4a18-9b82-6a395e97ba09
cache-control: no-store
pragma: no-cache
content-type: application/json; charset=utf-8
{
"error": "invalid_grant",
"error_description": "Token request rejected"
}Log request ID, UTC time, operation and status, never keys, secret-bearing bodies or ticket URLs.