Skip to main content

​
Error Handling

Gale returns consistent and descriptive error responses across all endpoints to help you debug and recover gracefully.

​
Standard Error Format

All errors follow this format: 
{
  "error": {
    "code": "validation_error",
    "message": "Validation failed: merchant_product_id is required.",
    "details": {
      "field_errors": {
        "merchant_product_id": ["This field is required"]
      }
    }
  }
}

​
HTTP Status Codes

Status CodeError CodeMeaningWhen It Happens
400bad_requestBad RequestMalformed JSON or missing required fields
401unauthorizedUnauthorizedMissing or invalid API key
403forbiddenForbiddenValid token but insufficient permissions
404not_foundNot FoundResource does not exist
409conflictConflictInvalid state change
422validation_errorValidation FailedField validation failed
429rate_limit_exceededToo Many RequestsRate limit exceeded
500internal_errorServer ErrorSomething went wrong on Gale’s side

​
Error Examples

​
Validation Error (422)

{
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "details": {
      "field_errors": {
        "line_items": ["At least one line item is required"],
        "customer.email": ["Invalid email format"]
      }
    }
  }
}

​
Unauthorized (401)

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

​
Not Found (404)

{
  "error": {
    "code": "not_found",
    "message": "Order not found"
  }
}

​
Rate Limited (429)

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please try again in 30 seconds."
  }
}
Response includes Retry-After header indicating seconds to wait.

​
Best Practices

  • Check status code first: Use HTTP status codes to determine error type
  • Parse error details: Check error.details.field_errors for specific validation failures
  • Implement retry logic: For 429 and 500 errors, retry with exponential backoff
  • Log errors: Store error responses for debugging