Error Codes

All API errors include a structured response with a code, message, and optional details.

Error Response Format

{
  "status": "error",
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": { /* additional context */ }
  }
}

Authentication Errors (401, 403)

Code	HTTP	Description	Retryable
`AUTH_ERROR`	401	Generic authentication failure	No
`AUTH_INVALID_TOKEN`	401	Token is invalid or malformed	No
`AUTH_TOKEN_EXPIRED`	401	Token has expired	Yes (refresh)
`AUTH_MISSING_TOKEN`	401	No Authorization header	No
`AUTH_INSUFFICIENT_PERMISSIONS`	403	Token lacks required permissions	No

Validation Errors (400)

Code	HTTP	Description	Retryable
`VALIDATION_ERROR`	400	Generic validation failure	No
`VALIDATION_MISSING_FIELD`	400	Required field not provided	No
`VALIDATION_INVALID_FORMAT`	400	Field format is invalid	No
`VALIDATION_OUT_OF_RANGE`	400	Value outside acceptable range	No

Resource Errors (404, 409)

Code	HTTP	Description	Retryable
`NOT_FOUND`	404	Resource not found	No
`RESOURCE_NOT_FOUND`	404	Specific resource does not exist	No
`CONFLICT`	409	Resource state conflict	No
`DUPLICATE_RESOURCE`	409	Resource already exists	No

Quota & Rate Limiting (429)

Code	HTTP	Description	Retryable
`QUOTA_EXCEEDED`	429	Monthly quota limit reached	Yes (after reset)
`RATE_LIMIT_EXCEEDED`	429	Too many requests per minute	Yes (after delay)

Quota headers included in response:

X-Quota-Used: Current usage
X-Quota-Limit: Maximum allowed
X-Quota-Reset: Reset timestamp
Retry-After: Seconds to wait (rate limit)

Plan & Feature Errors (403)

Code	HTTP	Description	Retryable
`PLAN_RESTRICTION`	403	Feature requires higher plan	No (upgrade)
`FEATURE_NOT_AVAILABLE`	403	Feature not in current plan	No (upgrade)
`UPGRADE_REQUIRED`	403	Must upgrade to access	No (upgrade)

Google API Errors (502, 503)

Code	HTTP	Description	Retryable
`GOOGLE_API_ERROR`	502	Google API returned an error	Yes
`GOOGLE_AUTH_ERROR`	502	Google authentication failed	Yes (reconnect)
`GOOGLE_QUOTA_EXCEEDED`	503	Google's rate limit hit	Yes (with delay)

Business Logic Errors (422)

Code	HTTP	Description	Retryable
`SYNC_ERROR`	422	Synchronization failed	Yes
`BUSINESS_RULE_VIOLATION`	422	Business rule prevented action	No
`INVALID_STATE`	422	Operation not valid in current state	No

Server Errors (500)

Code	HTTP	Description	Retryable
`INTERNAL_ERROR`	500	Unexpected server error	Yes
`DATABASE_ERROR`	500	Database operation failed	Yes
`CONFIGURATION_ERROR`	500	Server misconfiguration	No

SDK Error Handling

import { SynoveoClient, SynoveoError, ErrorCodes } from '@synoveo/sdk'

try {
  await client.posts.create(locationId, post)
} catch (error) {
  if (error instanceof SynoveoError) {
    switch (error.code) {
      case ErrorCodes.QUOTA_EXCEEDED:
        const resetAt = error.details?.resetAt
        console.log(`Quota resets at: ${resetAt}`)
        break

      case ErrorCodes.RATE_LIMIT_EXCEEDED:
        const retryAfter = error.details?.retryAfter
        await sleep(retryAfter * 1000)
        // Retry request
        break

      case ErrorCodes.PLAN_RESTRICTION:
        console.log(`Upgrade to ${error.details?.requiredPlan}`)
        break

      case ErrorCodes.GOOGLE_API_ERROR:
        console.log(`Google error: ${error.message}`)
        break
    }
  }
}

On this page