Errors
Errors
Every error is a single RFC 7807
problem document, served as application/problem+json. The HTTP status is
authoritative; the code is stable and safe to branch on.
Shape
{
"type": "https://bastos-cms.dev/errors/bad_request",
"title": "bad_request",
"status": 400,
"code": "bad_request",
"params": { "message": "missing `target_format` field" }
}| Field | Meaning |
|---|---|
type | Stable URI identifying the error class |
title | Short human-readable summary |
status | HTTP status code (mirrors the response status) |
code | Stable machine code — branch on this, not on title |
params | Optional context (e.g. message, limits) — present on some errors |
Every response also carries an x-request-id header. Quote it when reporting an
issue — it lets support trace the exact request.
Common codes
| Status | code | When |
|---|---|---|
400 | bad_request | Malformed multipart, missing required field, unsupported target_format |
401 | auth_required | Missing/invalid API key on a key-gated endpoint |
403 | forbidden | Authenticated but not allowed (e.g. another account's job) |
404 | not_found | Unknown route or job id |
413 | payload_too_large | File exceeds the per-tool size cap |
429 | rate_limited | Rate limit hit — see Rate limits (Retry-After) |
500 | internal | Unexpected server error — safe to retry with backoff |
Handling errors
http=$(curl -s -o body.json -w '%{http_code}' \
-X POST https://bastosconvert.com/api/v1/media/convert_audio \
-F file=@track.wav -F target_format=mp3)
case "$http" in
2*) echo "ok" ;;
429) echo "slow down: $(jq -r .code body.json)" ;;
4*) echo "client error: $(jq -r '.code + \" — \" + (.params.message // \"\")' body.json)" ;;
5*) echo "server error, retry later" ;;
esac