API v1

Errors, Retries & Limits

Understand Media2URL API error responses, idempotent retries, rate limits, quotas, upload limits, and safe backoff guidance.

Error Format

Errors use application/problem+json. Every problem includes a public type URL, title, HTTP status, detail, stable code, and request ID.

{
  "type": "https://api.media2url.com/v1/errors/rate_limit_exceeded",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded.",
  "code": "rate_limit_exceeded",
  "request_id": "req_example_123",
  "instance": "/v1/uploads/presign"
}

Use request_id when contacting support. It is not an authentication credential.

HTTP Status Codes

Common API Errors

Status	Meaning	Retry guidance
`400`	The request is malformed or missing a required field.	Fix the request; do not retry unchanged.
`401`	The API key is missing, invalid, revoked, or expired.	Rotate or correct the key.
`403`	The key lacks a scope, quota, plan, workspace, or policy access.	Check account state and permissions.
`404`	The resource is not available in the authenticated scope.	Verify the ID and account.
`409`	The resource or idempotency state conflicts with the request.	Reuse the original request or choose a new logical key.
`410`	An upload session or temporary resource expired or was consumed.	Request a new session.
`422`	The bytes or declared metadata failed validation.	Correct the file or metadata.
`429`	A short-window or monthly API limit was reached.	Honor Retry-After and use backoff.
`503`	A public API feature or authorization dependency is temporarily unavailable.	Retry cautiously with backoff if the operation is safe.

Retry Behavior

Rate-limit headers

Successful and rate-limited responses can include:

RateLimit-Limit: 120
RateLimit-Remaining: 117
RateLimit-Reset: 42
Retry-After: 42

Treat the returned headers as authoritative. Endpoint cost and account limits can make the remaining value decrease by more than one. Retry-After is the minimum wait for a rejected request when it is present.

Idempotency keys

Use an Idempotency-Key for finalization, replacement finalization, and imports when a retry could create a duplicate result:

Idempotency-Key: import-example-20260920-001

Keys are limited to 128 characters. Repeating the same key with the same request body is the safe retry pattern. Reusing a key for a different body can return 409 Conflict; create a new key for a new logical operation.

A safe retry loop

Parse the status and code from the problem response.
Retry only transient 429 or 503 failures, and honor Retry-After.
Use exponential backoff with a maximum attempt count.
For an upload session failure, request a new session when the session is expired or consumed.
Never retry invalid credentials, missing scopes, quota exhaustion, or malformed payloads unchanged.

Rate Limits

The API applies a short-window budget per external key and account. The default runtime budget is 120 weighted units per minute; operations can have a lower endpoint budget and different costs:

Operation cost	Weight
Light	1
Standard	2
Heavy	3
Import	5

The response headers are authoritative:

RateLimit-Limit: 120
RateLimit-Remaining: 118
RateLimit-Reset: 59

When the API rejects a request with 429, wait for Retry-After seconds before retrying. Use bounded exponential backoff and avoid synchronized retries from many workers.

Quota Limits

Monthly API allowance

The monthly API request allowance depends on the active account plan. Read GET /usage before large jobs and stop when requests.used approaches requests.limit.

curl --request GET \
  --url https://api.media2url.com/v1/usage \
  --header "Authorization: Bearer ${MEDIA2URL_API_KEY}"

The response reports API access, request usage and reset time, storage usage, and bandwidth usage. Do not hard-code a monthly allowance in your application; plan entitlements can change.

Request Limits

Upload and storage controls

Uploads are checked against the active account's file, storage, bandwidth, safety, privacy, and plan rules. A successful presign reserves capacity, and finalization commits it only after the bytes pass validation. If finalization fails, the reservation is released according to the API workflow.

The declared size must match the uploaded bytes. A checksum is strongly recommended for files that must be verified end to end.

Other published bounds

Asset list limit defaults to 20 and accepts at most 100.
API key expiry accepts a whole number from 1 to 365 days, or no expiry.
An account can have at most 10 active external API keys.
Idempotency-Key accepts at most 128 characters.
Upload and import sessions are temporary and single-use where the endpoint says so.

Designing a Reliable Client

Keep concurrency below the returned remaining budget.
Queue large imports instead of starting an unbounded burst.
Cache stable asset metadata in your own application, but treat delivery URLs and access state as authoritative when you use them.
Read usage and rate-limit headers before batch work.
Stop and surface a clear operator action for quota, plan, scope, and policy failures.

Return to Media2URL API v1 overview and authentication, or continue with Uploads, imports, and jobs and Assets, versions, and folders.