Errors

When something goes wrong, the Macrofy API returns a consistent error structure.

Error format

All errors follow this structure:

{
  "error": {
    "code": "invalid_api_key",
    "message": "API key is missing or invalid.",
    "requestId": "req_abc123",
    "details": {}
  }
}

Name
code
Type
string
Description
Machine-readable error code. Use this for programmatic handling.
Name
message
Type
string
Description
Human-readable description of the error.
Name
requestId
Type
string
Description
Unique identifier for the request. Include this when contacting support.
Name
details
Type
object
Description
Additional context (e.g., validation errors, retry timing).

HTTP status codes

Name
200
Type
OK
Description
Request succeeded.
Name
400
Type
Bad Request
Description
Invalid request parameters.
Name
401
Type
Unauthorized
Description
Missing or invalid API key.
Name
404
Type
Not Found
Description
Resource not found (e.g., barcode, job ID).
Name
429
Type
Too Many Requests
Description
Rate limit exceeded. See Rate limits.
Name
500
Type
Internal Server Error
Description
Server error. Retry with exponential backoff.

Error codes

Authentication

Name
invalid_api_key
Description
API key is missing or invalid.
Name
expired_api_key
Description
API key has been revoked or expired.

Food search

Name
invalid_query
Description
Search query is empty or malformed.
Name
no_results
Description
No foods matched the search query.

Barcode lookup

Name
barcode_not_found
Description
No food found for the given barcode.
Name
invalid_barcode
Description
Barcode format is invalid.

Image scan

Name
scan_job_not_found
Description
Job ID does not exist or has expired.
Name
scan_failed
Description
Image analysis failed. Check image quality.
Name
invalid_content_type
Description
Content type must be image/jpeg or image/png.
Name
upload_expired
Description
Signed upload URL has expired. Create a new scan job.

Rate limiting

Name
rate_limit_exceeded
Description
Too many requests. See details.retryAfter for wait time.

SDK error handling

import { MacrofyError } from '@macrofy/node'

try {
  await macrofy.lookupBarcode({ upc: 'invalid' })
} catch (err) {
  if (err instanceof MacrofyError) {
    switch (err.code) {
      case 'barcode_not_found':
        // Handle missing barcode
        break
      case 'rate_limit_exceeded':
        // Wait and retry
        await sleep(err.details.retryAfter * 1000)
        break
      default:
        console.error(err.message)
    }
  }
}