Error codes

Reference guide for HTTP status codes and error responses returned by the Measura API.

Overview

The Measura API uses standard HTTP status codes to indicate the success or failure of a request. When an error occurs, the response body includes detailed error information in a consistent format.

Error response format

All error responses follow a consistent structure:

{
  "success": false,
  "data": null,
  "error": {
    "code": "error_code",
    "message": "Human-readable error message",
    "details": { ... }
  },
  "meta": { ... },
  "requestId": "optional-request-id"
}

Note

The requestId field can be used when contacting support to help identify and debug specific requests. For detailed information about the error object structure, see the ApiError object documentation.

HTTP status codes

The following HTTP status codes are used by the API:

Status codeDescriptionCommon causes
400Bad RequestThe request was malformed or contained invalid parameters. Check your request parameters and try again.
401UnauthorizedInvalid or missing API key. Verify your API key is correct and properly formatted as {keyId}:{secret}.
404Not FoundThe requested resource was not found. Verify the product ID, variant ID, or endpoint path is correct.
429Too Many RequestsRate limit exceeded. Wait before making additional requests. Check the Retry-After header if provided.
500Internal Server ErrorAn unexpected error occurred on the server. If this persists, contact support with the requestId.

Error codes

The error.code field contains a specific error code that can be used for programmatic error handling:

Error codeHTTP statusDescription
unauthorized401Invalid or missing API key. The API key may be expired, inactive, or incorrectly formatted.
bad_request400The request parameters are invalid. Common causes include invalid product ID format, invalid limit value, or missing required parameters.
not_found404The requested resource was not found. This may occur when a product or variant doesn't exist, or when a variant doesn't belong to the specified product.
rate_limited429Too many requests in a given time period. Rate limiting may be applied to prevent abuse. Wait before retrying.
internal_error500An unexpected server error occurred. This is typically a temporary issue. If it persists, contact support.

Error response examples

401 Unauthorized

{
  "success": false,
  "data": null,
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized",
    "details": {}
  },
  "meta": {},
  "requestId": "req_abc123"
}

400 Bad Request

{
  "success": false,
  "data": null,
  "error": {
    "code": "bad_request",
    "message": "Invalid product ID format",
    "details": {
      "field": "productId",
      "reason": "Expected a valid Shopify product REST ID"
    }
  },
  "meta": {},
  "requestId": "req_abc123"
}

404 Not Found

{
  "success": false,
  "data": null,
  "error": {
    "code": "not_found",
    "message": "Product not found",
    "details": {
      "resource": "product",
      "id": "123"
    }
  },
  "meta": {},
  "requestId": "req_abc123"
}

429 Too Many Requests

{
  "success": false,
  "data": null,
  "error": {
    "code": "rate_limited",
    "message": "Too Many Requests",
    "details": {
      "retryAfter": 60
    }
  },
  "meta": {},
  "requestId": "req_abc123"
}

500 Internal Server Error

{
  "success": false,
  "data": null,
  "error": {
    "code": "internal_error",
    "message": "Internal Server Error",
    "details": {}
  },
  "meta": {},
  "requestId": "req_abc123"
}

Handling errors

When handling errors in your application, consider the following:

  • 401 Unauthorized: Check your API key and ensure it's properly formatted. Verify the key is active and not expired.
  • 400 Bad Request: Review the request parameters and ensure they match the expected format. Check the error.details field for specific validation errors.
  • 404 Not Found: Verify the resource ID exists and belongs to the shop associated with your API key.
  • 429 Too Many Requests: Implement exponential backoff when retrying. Check for a Retry-After header or error.details.retryAfter value.
  • 500 Internal Server Error: These are typically temporary. Retry the request after a short delay. If the error persists, contact support with the requestId.