Responses

Every request returns a standard HTTP status code along with a JSON body.

Below are the possible responses you may encounter.

Usage and limits

Responses include the usage of your organization in meta.usage, next to your limits in meta.limits. Both objects use the same keys, so you can compute what is left with limits.calls - usage.calls.

rate — Requests in the current minute, and the limit per minute.
calls — Requests this month, and the limit per month.
credits — Credits used this month, and the credits per month.

Usage includes the current request. meta.credits holds the credits charged for the current request only.

200 OK

The request was successful.

{
	success: true,
	meta: {
		usage: {
			rate: 1,
			calls: 1,
			credits: 1
		},
		limits: {
			rate: 100,
			calls: 10000,
			credits: 5000
		},
		credits: 1,
		path: "/v1/weather/forecast",
		parameters: {
			lat: 52.02,
			lon: 5.16,
			radius: 1000,
			language: "en"
		}
	},
	data: {
		...
	}
}

400 Missing required parameters

{
	success: false,
	meta: {
		credits: 0
	},
	error: {
		message: "Missing required parameters",
		path: "/v1/weather/forecast",
		missingParameters: [
		   "lat",
		   "lon"
		]
	}
}

400 Missing API key

{
	success: false,
	meta: {
		credits: 0
	},
	error: {
		message: "Missing API key, please provide api_key=<your-api-key>",
		path: "/v1/weather/forecast"
	}
}

401 Invalid API key

{
	success: false,
	meta: {
		credits: 0
	},
	error: {
		message: "Invalid API key",
		path: "/v1/weather/forecast"
	}
}

404 Route not found

{
	success: false,
	meta: {
		credits: 0
	},
	error: {
		message: "Route not found",
		path: "/v1/weather/forecast/unknown"
	}
}

429 Rate limit

Returned when the requests per minute limit is reached. The request is not counted in your usage.

{
	success: false,
	meta: {
		usage: {
			rate: 100,
			calls: 4210,
			credits: 4210
		},
		limits: {
			rate: 100,
			calls: 10000,
			credits: 5000
		},
		credits: 0
	},
	error: {
		message: "Rate limit 100 calls/minute reached. Slow down and try again later.",
		path: "/v1/weather/forecast"
	}
}

429 Call limit

Returned when the requests per month limit is reached. The request is not counted in your usage.

{
	success: false,
	meta: {
		usage: {
			rate: 12,
			calls: 10000,
			credits: 4870
		},
		limits: {
			rate: 100,
			calls: 10000,
			credits: 5000
		},
		credits: 0
	},
	error: {
		message: "Call limit 10000 calls/month reached. Please raise your limit or wait until next month.",
		path: "/v1/weather/forecast"
	}
}

429 No credits left

{
	success: false,
	meta: {
		credits: 0
	},
	error: {
		message: "No credits left. Please add more credits to your account."
	}
}

500 Internal Server Error

{
	success: false,
	meta: {
		usage: {
			rate: 1,
			calls: 1,
			credits: 0
		},
		limits: {
			rate: 100,
			calls: 10000,
			credits: 5000
		},
		credits: 0
	},
	error: {
		message: "Error executing route",
		description: "Custom error message",
		path: "/test/error_custom"
	}
}