Error Codes

The Bitcore APIs utilize HTTP status codes to indicate the outcome of requests. 2XX status codes signify successful operations, while 4XX and 5XX status codes indicate errors.

4XX status codes represent client errors, meaning the request was malformed or unauthorized, often due to issues like invalid parameters or authentication failures. In such cases, it's essential to review the response body for specific error codes and messages to understand the nature of the problem.

5XX status codes indicate server errors, suggesting that an issue occurred on the server side while processing the request. If you encounter a 5XX error, it may be a temporary issue, and retrying the request after some time is advisable. Always check the response body for additional details regarding the error.

---

General Error Response Format

Each error response follows a standard JSON format. Depending on the error type, optional fields like errors, details, extra_info may be included.

Minimal Format for Simple Errors

{   
  "status": <HTTP_STATUS_CODE>,
  "success": false,
  "error_code": "<ERROR_CODE>",
  "message": "<HUMAN_READABLE_MESSAGE>"
}

Extended Format

{
  "status": <HTTP_STATUS_CODE>,
  "success": false,
  "error_code": "<ERROR_CODE>",
  "message": "<HUMAN_READABLE_MESSAGE>",
  "errors": [
    {
      "field": "<FIELD_NAME>",
      "message": "<SPECIFIC_ERROR_MESSAGE>"
    }
  ],
  "details": {
    "hint": "<SUGGESTED_FIX_OR_DETAILS>",
    "reference": "<DOCUMENTATION_LINK>",
    "possible_causes": ["<POSSIBLE_CAUSE_1>", "<POSSIBLE_CAUSE_2>"]
  },
  "metadata": {
    "request_id": "<UNIQUE_REQUEST_IDENTIFIER>",
    "timestamp": "<ISO_8601_UTC_TIMESTAMP>",
    "retry_after": <SECONDS>,
    "throttle_info": <RATE_LIMITING_INFO>
  }
}

Extended Error Format Description

Some API error responses include an extended format to help with debugging and handling:

• metadata: General request info like request_id, retry_after, or rate-limit indicators.

• errors: Field-specific validation issues (e.g., missing or invalid input).

• details: Helpful hints or links to fix the issue.

  {
    "hint": "Ensure the API key is valid",
    "reference": "https://docs.example.com/errors/401"
  }

• throttle_info (only if rate-limited): Shows current rate limit status.

  {
    "limit": 500,
    "remaining": 10,
    "reset_in": 120,
    "policy": "500 requests per 10 minutes"
  }

---

Client Errors (4xx)

Code	Status Name	Error Code	Meaning
400	Bad Request	INVALID_INPUT, INVALID_FILE_TYPE, FILE_TOO_LARGE, MALFORMED_REQUEST	The request is malformed or has invalid parameters.
401	Unauthorized	TOKEN_EXPIRED, TOKEN_REVOKED, INVALID_CREDENTIALS, INVALID_TOKEN, UNAUTHORIZED_ACCESS	Authentication is required or failed.
402	Payment Required	INSUFFICIENT_BALANCE, PAYMENT_REQUIRED, PAYMENT_FAILED, INVOICE_OVERDUE	Payment-related issues.
403	Forbidden	INSUFFICIENT_PERMISSIONS	User does not have permission to access.
404	Not Found	RESOURCE_NOT_FOUND, FILE_NOT_FOUND	The requested resource does not exist.
405	Method Not Allowed	METHOD_NOT_ALLOWED	The HTTP method used is not allowed for this endpoint.
409	Conflict	BUSINESS_RULE_VIOLATION, RESOURCE_ALREADY_EXISTS	Conflict due to duplicate records or business rule violation. Example: This asset already has an associated NFT. Onboarding not completed. Minting is restricted.
415	Unsupported Media Type	UNSUPPORTED_MEDIA_TYPE, INVALID_CONTENT_TYPE, UNSUPPORTED_FILE_FORMAT	The request has an unsupported Content-Type (e.g., client sends XML when JSON is expected).
426	Upgrade Required	API_VERSION_DEPRECATED, API_VERSION_NOT_SUPPORTED	The client must switch to a newer protocol version. Useful for enforcing API versioning.
429	Too Many Requests	RATE_LIMIT_EXCEEDED, THROTTLE_LIMIT_REACHED, API_QUOTA_EXCEEDED	Rate limiting triggered due to excessive requests.

---

Server Errors (5xx)

Code	Status Name	Error Code	Meaning
500	Internal Server Error	INTERNAL_SERVER_ERROR	A generic server error occurred.
502	Bad Gateway	BAD_GATEWAY	Received an invalid response from an upstream server.
503	Service Unavailable	SERVICE_UNAVAILABLE, MAINTENANCE_MODE	The server is temporarily overloaded or under maintenance.
504	Gateway Timeout	GATEWAY_TIMEOUT	The server did not respond in time.

---

Example Error Responses

429 - Too Many Requests

{
  "status": 429,
  "success": false,
  "error_code": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests. Please try again later.",
  "metadata": {
    "retry_after": 60,
    "request_id": "def789",
    "throttle_info": {
      "limit": 500,
      "remaining": 0,
      "reset_in": 60,
      "policy": "500 requests per minute"
    },
    "timestamp": "2025-03-22T12:10:00Z"
  }
}

401 - Unauthorized

{
  "status": 401,
  "success": false,
  "error_code": "TOKEN_EXPIRED",
  "message": "Invalid API token. Please authenticate.",
  "metadata": {
    "request_id": "abc123",
    "timestamp": "2025-03-22T12:00:00Z"
  }
}