Errors

The Straply API uses standard HTTP status codes and returns structured error responses.

Error response format

All errors follow the same JSON structure:

{
  "error": {
    "code": "not_found",
    "message": "Property not found.",
    "status": 404
  }
}

Error codes

400 Bad Request

Returned when the request is malformed or contains invalid parameters.

{
  "error": {
    "code": "bad_request",
    "message": "Invalid value for parameter 'minPrice': must be a positive integer.",
    "status": 400
  }
}

Common causes:

• Missing required parameters
• Invalid parameter types or formats
• Out-of-range values

401 Unauthorized

Returned when the API key is missing, invalid, or revoked.

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

Common causes:

• Missing Authorization header
• Malformed Bearer token
• Revoked or expired API key

403 Forbidden

Returned when the API key does not have permission for the requested resource.

{
  "error": {
    "code": "forbidden",
    "message": "Your plan does not include bulk downloads. Upgrade to Pro or Enterprise.",
    "status": 403
  }
}

404 Not Found

Returned when the requested resource does not exist.

{
  "error": {
    "code": "not_found",
    "message": "Property not found.",
    "status": 404
  }
}

429 Too Many Requests

Returned when you have exceeded your rate limit. See Rate Limits for details.

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Daily lookup limit exceeded. Resets at midnight UTC.",
    "status": 429
  }
}

The response includes headers indicating your limit status:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1741564800

500 Internal Server Error

Returned when something unexpected goes wrong on our end.

{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred. Please try again.",
    "status": 500
  }
}

If you receive a 500 error repeatedly, contact support with the X-Request-Id header value from the response.

503 Service Unavailable

Returned during planned maintenance or temporary outages.

{
  "error": {
    "code": "service_unavailable",
    "message": "The API is temporarily unavailable. Please try again in a few minutes.",
    "status": 503
  }
}

Handling errors

We recommend implementing retry logic with exponential backoff for 429, 500, and 503 errors. Do not retry 400, 401, 403, or 404 errors as they will not resolve without changes to your request.