Errors, Status Codes & Rate Limits

Marquatica APIs use standard HTTP status codes and structured error responses to communicate errors clearly. This guide explains error handling and rate limiting across all API versions.

HTTP Status Codes

Marquatica uses standard HTTP status codes to indicate the success or failure of API requests. The following table lists all status codes you may encounter:

Status Code Meaning Description
200 OK Request completed successfully
201 Created Resource created successfully (warranty creation)
400 Bad Request Invalid parameters or missing required fields
401 Unauthorized Missing or invalid authentication
403 Forbidden Insufficient permissions (wrong brand or endpoint access)
404 Not Found Requested resource doesn't exist
409 Conflict Resource already exists (e.g., duplicate HIN for a brand)
422 Unprocessable Entity Input format invalid (e.g., invalid HIN format)
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Unexpected server error

Error Response Formats

Legacy and v1 APIs use slightly different error response formats. Ensure your client handles both formats properly.

Legacy API Errors (Dealer Locator, Lead Submission)

Simple error responses for basic requests:

{
  "error": "Brand parameter is required",
  "version": "0.1.1"
}

For lead submission validation errors with detailed field information:

{
  "status": "error",
  "message": "Invalid submission",
  "errors": [
    {
      "field": "contact.contact_email",
      "message": "Email address is required"
    }
  ],
  "version": "0.1.1"
}

Warranty API (v1) Errors

All Warranty API errors follow a consistent, structured format:

{
  "success": false,
  "status": 400,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

Warranty API Error Codes

The Warranty API uses specific error codes to categorize different types of failures. Reference this table to handle errors appropriately in your client:

Error Code HTTP Status Description
VALIDATION_ERROR 400 Invalid input data or missing required fields
INVALID_CREDENTIALS 401 Wrong email or password
TOKEN_EXPIRED 401 JWT access token has expired — use refresh token
ENDPOINT_NOT_PERMITTED 403 Your API user does not have access to this endpoint
BRAND_NOT_PERMITTED 403 Your API user does not have access to this brand
WARRANTY_NOT_FOUND 404 No warranty found with the given HIN (for your brands)
DUPLICATE_HIN 409 A warranty with this HIN already exists for this brand
INVALID_HIN_FORMAT 422 HIN must be exactly 12 alphanumeric characters

Rate Limits

Marquatica implements rate limiting to ensure fair usage and platform stability. Rate limits are applied at different scopes depending on the API version:

Legacy APIs

  • 50 requests per minute per API token

Warranty API (v1)

  • 50 requests per minute per authenticated user
When you exceed the rate limit, you'll receive a 429 Too Many Requests response. Wait and retry after a short delay.
Rate limits are applied per API token (legacy) or per authenticated user (v1). Different API tokens or users have independent rate limits.

Best Practices

Follow these best practices to handle errors gracefully and make efficient use of the APIs:

  • Handle errors gracefully — Check the HTTP status code first, then examine the error body for specific details.
  • Implement exponential backoff — For rate limit errors (429), wait a short time before retrying. Increase the wait time exponentially on subsequent retries.
  • Store and reuse your JWT access token — Don't re-authenticate on every request. Cache your token until it expires.
  • Use the refresh token flow — Get new access tokens using your refresh token without requiring users to re-enter credentials.
Previous Warranty API
On this page