Error Handling

Understand PlaceIQ API error codes and how to handle them.

PlaceIQ uses standard HTTP response codes and returns detailed error messages to help you debug issues quickly.

HTTP Status Codes

Code	Description
200	Success - The request completed successfully
201	Created - A new resource was created
400	Bad Request - Invalid parameters or malformed request
401	Unauthorized - Missing or invalid API key
403	Forbidden - API key doesn't have required permissions
404	Not Found - The requested resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Something went wrong on our end

Error Response Format

All errors return a consistent JSON structure:

JSON

{
  "error": {
    "code": "error_code",
    "message": "Human-readable error message",
    "status": 400,
    "details": {
      "field": "Additional context about the error"
    }
  }
}

Common Error Codes

Code	Status	Description
`missing_api_key`	401	No API key was provided in the Authorization header
`invalid_api_key`	401	The API key is malformed or doesn't exist
`revoked_api_key`	401	The API key has been revoked
`insufficient_permissions`	403	Your plan doesn't include this feature
`area_not_found`	404	The specified area doesn't exist
`invalid_parameter`	400	A request parameter is invalid
`rate_limit_exceeded`	429	You've exceeded your rate limit
`quota_exceeded`	429	You've used all your monthly API calls
`internal_error`	500	An unexpected error occurred

Error Examples

Invalid API Key

JSON

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has expired",
    "status": 401
  }
}

Invalid Parameter

JSON

{
  "error": {
    "code": "invalid_parameter",
    "message": "Invalid value for parameter 'limit'",
    "status": 400,
    "details": {
      "parameter": "limit",
      "value": "-5",
      "constraint": "must be between 1 and 100"
    }
  }
}

Rate Limit Exceeded

JSON

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please wait before making more requests.",
    "status": 429,
    "details": {
      "limit": 100,
      "window": "60s",
      "retry_after": 45
    }
  }
}

Handling Errors

async function fetchArea(areaId) {
  const response = await fetch(
    `https://api.placeiq.co/v1/areas/${areaId}`,
    { headers: { "Authorization": "Bearer YOUR_API_KEY" } }
  );

  if (!response.ok) {
    const { error } = await response.json();

    switch (error.code) {
      case "area_not_found":
        console.error(`Area ${areaId} not found`);
        break;
      case "rate_limit_exceeded":
        // Wait and retry
        await sleep(error.details.retry_after * 1000);
        return fetchArea(areaId);
      default:
        throw new Error(error.message);
    }
  }

  return response.json();
}