Error handling & request limiting

Authentication errors

Scenario	HTTP Status	Error Code
Missing or empty Authorization header	401	INVALID_AUTHENTICATION
Invalid or expired access token	401	INVALID_AUTHENTICATION
Malformed credentials	401	INVALID_AUTHENTICATION

Example:

{
  "meta": {
    "status": "FAILURE"
  },
  "data": [],
  "errors": [
    {
      "code": "INVALID_AUTHENTICATION",
      "message": "Access token is invalid, expired, or missing."
    }
  ]
}

Request limit

📘
Note that the request limit does not indicate the rate limit in availability Search. This only indicates the query request limit for Content 2.0 API.

When rate limited:
- HTTP status: 429 Too Many Requests
- Response includes a Retry-After header indicating how many seconds to wait before retrying.
  Example rate limit response:
Example:

{  
  "meta": {  
    "status": "FAILURE"  
  },  
  "data": [],  
  "errors": [  
    {  
      "code": "RATE_LIMIT_EXCEEDED",  
      "message": "Rate limit exceeded, please retry after some time",  
      "retryAfter": 5  
    }  
  ]  
}

Best practices:
- Implement exponential backoff with jitter when you receive a 429.
- Spread requests evenly over time rather than bursting.
- If you need higher throughput, contact your Agoda account manager to discuss your requirements.

HTTP status codes

Status Code	Meaning	Action
200	Success (or partial success)	Process response. Inspect meta.status.
400	Bad Request — invalid parameters	Do not retry. Fix the request.
401	Unauthorized — invalid token	Obtain a new access token.
429	Rate limit exceeded	Wait for Retry-After duration, then retry.
500	Internal server error	Retry with exponential backoff.
503	Service temporarily unavailable	Retry with exponential backoff.

Application-level error codes

Error Code	HTTP	Meaning	Action
AUTHENTICATION_FAILED	401	Token is invalid or expired	Verify or refresh token
RATE_LIMIT_EXCEEDED	429	Too many requests	Wait and retry
INVALID_PARAMETER	400	Validation error	Check error message
INVALID_PROPERTY_IDS	400	IDs are malformed	Ensure positive integers
PROPERTY_FETCH_ERROR	200*	Some properties failed	Retry failed IDs separately
INTERNAL_ERROR	500	Unexpected server error	Retry after a wait time

*PROPERTY_FETCH_ERROR returns HTTP 200 with meta.status: "PARTIAL_SUCCESS"

Partial success

A response with meta.status: "PARTIAL_SUCCESS" means some properties were fetched successfully while others failed. You can handle this scenario with the following steps.

Process and store the successful properties from data.
Collect the failed property IDs from errors[].ids.
Retry the failed IDs in a separate request after a short delay.