Error catalogue

Every error is an application/problem+json document with a stable code. This list is generated from the same registry the API uses, so it names every code the API can return.

How to handle errors

invalid_request
HTTP 400
Invalid request
Meaning
One or more parameters are missing, out of range or not accepted by this endpoint.
What to do
Fix the parameters listed in invalid_params and send the request again.
Problem type
https://developers.i4sea.com.br/errors/invalid_request
key_in_query
HTTP 400
API key sent in the query string
Meaning
An API key, or a value that looks like one, was sent in the URL query string.
What to do
Send the key only in the Authorization: Bearer header, and rotate the exposed key.
Problem type
https://developers.i4sea.com.br/errors/key_in_query
unauthenticated
HTTP 401
Missing or invalid API key
Meaning
The key is missing, malformed, unknown, revoked or expired. One code covers all cases, so the response reveals nothing about the key.
What to do
Check that the request sends a current key as Authorization: Bearer i4s_live_....
Problem type
https://developers.i4sea.com.br/errors/unauthenticated
insufficient_scope
HTTP 403
Key lacks the required scope
Meaning
The key is valid but was not granted the scope this endpoint requires.
What to do
Ask i4sea for a key with the scope named in detail.
Problem type
https://developers.i4sea.com.br/errors/insufficient_scope
subscription_inactive
HTTP 403
No active API subscription
Meaning
The key's company has no API subscription, or its subscription is suspended.
What to do
Contact i4sea to activate the API subscription.
Problem type
https://developers.i4sea.com.br/errors/subscription_inactive
product_not_in_plan
HTTP 403
Product not included in the plan
Meaning
The endpoint belongs to a product that the company's API plan does not include.
What to do
Contact i4sea to add the product to the plan.
Problem type
https://developers.i4sea.com.br/errors/product_not_in_plan
outside_coverage
HTTP 403
Location outside contracted coverage
Meaning
The requested point lies outside the company's contracted regions. No units are charged.
What to do
Query a point inside the contracted regions, or contact i4sea to extend the coverage.
Problem type
https://developers.i4sea.com.br/errors/outside_coverage
not_found
HTTP 404
Not found
Meaning
The route does not exist in this version of the API.
What to do
Check the path against the endpoint reference.
Problem type
https://developers.i4sea.com.br/errors/not_found
payload_too_large
HTTP 413
Payload too large
Meaning
The request body exceeds the size accepted by the API.
What to do
Reduce the request body.
Problem type
https://developers.i4sea.com.br/errors/payload_too_large
rate_limited
HTTP 429
Too many requests
Meaning
The key exceeded its plan's requests-per-minute limit.
What to do
Wait the number of seconds in Retry-After before sending more requests.
Problem type
https://developers.i4sea.com.br/errors/rate_limited
quota_exceeded
HTTP 429
Monthly quota exceeded
Meaning
The company used up its plan's monthly units. The quota resets on the 1st of the month, UTC.
What to do
Wait for the reset given in Retry-After, or contact i4sea to raise the quota.
Problem type
https://developers.i4sea.com.br/errors/quota_exceeded
internal_error
HTTP 500
Internal error
Meaning
The API failed to process a valid request.
What to do
Retry later; if it persists, contact i4sea quoting the request_id.
Problem type
https://developers.i4sea.com.br/errors/internal_error
provider_unavailable
HTTP 503
Forecast provider unavailable
Meaning
The forecast could not be resolved right now because an upstream source is unavailable.
What to do
Retry after the number of seconds in Retry-After.
Problem type
https://developers.i4sea.com.br/errors/provider_unavailable
timeout
HTTP 504
Request timed out
Meaning
The request took longer than the API allows.
What to do
Retry; if it repeats, request fewer hours or variables.
Problem type
https://developers.i4sea.com.br/errors/timeout