Errors

The Bitcompare API uses conventional HTTP status codes and returns structured JSON error responses.

Status codes

Name
200 OK
Description
The request succeeded.
Name
201 Created
Description
The resource was created successfully.
Name
204 No Content
Description
The request succeeded with no response body.
Name
400 Bad Request
Description
The request was malformed — missing a required parameter or invalid query value.
Name
401 Unauthorized
Description
Authentication is required or the provided credentials are invalid.
Name
403 Forbidden
Description
The authenticated user does not have permission to access the resource.
Name
404 Not Found
Description
The requested resource does not exist.
Name
409 Conflict
Description
The request conflicts with the current state of the resource (e.g., duplicate entry).
Name
422 Unprocessable Entity
Description
Request parameters failed validation.
Name
429 Too Many Requests
Description
You have exceeded the rate limit for this endpoint.
Name
500 Internal Server Error
Description
An unexpected error occurred on the server.
Name
502 Bad Gateway
Description
An upstream service returned an invalid response.
Name
503 Service Unavailable
Description
The service is temporarily unavailable (e.g., stale data source).

Error shape

All error responses follow a consistent JSON structure. Errors are nested under an error object.

Name
error.message
Type
string
Description
A human-readable description of what went wrong.
Name
error.code
Type
string
Description
A machine-readable error code (e.g., VERSION_REQUIRED, NOT_FOUND, VALIDATION_ERROR).

Error response

{
  "error": {
    "message": "API version required. Specify version in URL (/api/v1/ or /v1/) or Accept-Version header.",
    "code": "VERSION_REQUIRED"
  }
}

Request parameters are validated on the server using Zod schemas. When validation fails, the response uses status 422 with the VALIDATION_ERROR code. An errors object maps field names to their error messages.

Name
error.message
Type
string
Description
The first validation error message.
Name
error.code
Type
string
Description
Always VALIDATION_ERROR for validation failures.
Name
error.errors
Type
object
Description
A map of field names to arrays of error messages.

Validation error response (422)

{
  "error": {
    "message": "Required",
    "code": "VALIDATION_ERROR",
    "errors": {
      "query.symbol": ["Required"]
    }
  }
}

Common error codes

Name
VERSION_REQUIRED
Description
The request URL does not include a version prefix (e.g., /api/v1/).
Name
NOT_FOUND
Description
The requested resource (coin, symbol, rate) was not found.
Name
BAD_REQUEST
Description
The request was malformed or missing required parameters.
Name
VALIDATION_ERROR
Description
One or more request parameters failed schema validation (status 422).
Name
RATE_LIMIT_EXCEEDED
Description
Too many requests — slow down or wait for the rate limit window to reset.
Name
UNAUTHORIZED
Description
Authentication is required to access this resource.
Name
FORBIDDEN
Description
The authenticated user lacks permission for this action.
Name
CONFLICT
Description
The request conflicts with existing state (e.g., duplicate resource).
Name
DATABASE_ERROR
Description
An internal database error occurred.
Name
EXTERNAL_SERVICE_ERROR
Description
An upstream service (e.g., CoinGecko) returned an error.
Name
SERVICE_UNAVAILABLE
Description
The service is temporarily unavailable.