Errors

The Carapis API uses standard HTTP status codes and returns a consistent JSON error object on failure — an error with a machine-readable code and a human message. Check the status code first, then branch on error.code.

Error shape

Every error response shares the same body:


{
  "error": {
    "code": "invalid_source",
    "message": "Unknown source slug. See the platforms page for valid values."
  }
}

Status codes

Status	Meaning	Typical cause
`400 Bad Request`	Malformed request	Invalid query parameter value or syntax.
`401 Unauthorized`	Missing or invalid key	No `Authorization` header, or a bad key. See Authentication.
`403 Forbidden`	Not permitted	Valid key without access to the resource or plan feature.
`404 Not Found`	No such resource	Unknown endpoint or listing id.
`422 Unprocessable Entity`	Validation failed	A parameter is the wrong type or out of range.
`429 Too Many Requests`	Rate limited	Over your plan’s quota — see Rate limits.
`500 Internal Server Error`	Server error	Transient issue on the Carapis side; retry.

Handling errors

Python


import requests
 
resp = requests.get(
    "https://api.carapis.com/v2/listings",
    params={"source": "encar", "limit": 20},
    headers={"Authorization": f"Bearer {API_KEY}"},
)
 
if resp.ok:
    data = resp.json()
else:
    err = resp.json().get("error", {})
    print(resp.status_code, err.get("code"), err.get("message"))

Recommendations

Always check the HTTP status before parsing the body as success.
Retry 429 and 500 with exponential backoff; do not retry 400, 401, 403, 404 or 422 — fix the request instead.
Log error.code so you can distinguish causes programmatically.

Errors

Error shape

Status codes

Handling errors

Python

JavaScript

Recommendations

Platforms

Docs

Solutions

Company