Skip to main content
Flatpeak uses HTTP status codes to indicate the success or failure of requests.
CodeDescription
2XXIndicates success.
4XXIndicates an invalid request. (error type: invalid_request)
429Indicates too many requests. (error type: rate_limit)
5XXindicates Flatpeak-related issues (error type: api_error).

​
Error object

When an error needs to be returned in an API response, Flatpeak uses a standardised error object across all endpoints: 
{
  "object": "error",
  "live_mode": false,
  "context": "connect.postal_address_capture",
  "type": "invalid_request",
  "code": "country_code_missing",
  "message": "Country code is required",
  "connect_token": "cot_6587fa4362341be5b524de3b",
  "time_created": "2022-01-24T14:15:22.003"
}
PropertyDescription
objectIndicates API object type, i.e. error.
live_modeIndicates if live or test mode API key was used.
contextIndicates error context. It provides information on which service and method has failed. For example, connect.postal_address_capture or api.location_create.
typeIndicates error type; possible values are invalid_request - when your request is invalid. And api_error when the Flatpeak service cannot process the request (these are rare).
codeConnect-related error codes are listed in the Connect section of api reference under the code sample of every page. General API-related error codes are listed in the API error codes table later on this page. Example: country_code_missing.
messageError description in the English language. Example: Country code is required.
connect_tokenThe Connect token used to make the request resulted in an error.
time_createdTimestamp when this error occurred.

​
Important errors you must support

Your system must handle error codes related to energy price unavailability and cases where your Flatpeak account is disabled.

​
Price unavailability errors

When energy price data is not available, Flatpeak returns a 422 error for any endpoint that depends on price data, including retrieve a price, schedule by duration, schedule by price limit, and schedule by amount of energy. 
{
  "object": "error",
  "type": "invalid_request",
  "context": "api.price_get",
  "code": "no_tariff_connected",
  "message": "No tariff connected for IMPORT direction",
  "time_created": "2025-01-01T00:00:00Z"
}
  • The no_tariff_connected code indicates that no tariff is connected to the queried location. Note that IMPORT and EXPORT tariffs are treated separately. See Tariff categories, contexts, and energy flow directions.
  • The pending_connect code indicates that Flatpeak Connect is accessing the customer’s tariff for the first time and the connection is pending. See Tariff connection pending.
  • The no_price_data code indicates that Flatpeak was unable to retrieve price data for an extended period and has already emitted the tariff.fetch.failed webhook. Review the Required webhooks article for more information.
When you receive any of these errors, we recommend not to retry the same request more frequently than once every 15 minutes.

​
Account disabled error

When your account is out of subscription or is disabled for any other reason, you will receive an error 422 when trying to access any API endpoint.
Acount disabled error example
{
	"object": "error",
	"type": "invalid_request",
	"code": "account_disabled",
	"message": "Your account is disabled.",
	"time_created": "2026-01-29T17:11:52Z"
}
When it happens:
  • Go to Dashboard > Settings > Billing to restore your subscription
  • Alternatively, contact support

​
Rate limiting (429) error

Flatpeak enforces rate limits to ensure platform stability. If you exceed the allowed request rate, the API returns a 429 error.
Rate limit error example
{
  "object": "error",
  "type": "rate_limit",
  "code": "too_many_requests",
  "message": "Too many requests. Please retry after a short delay.",
  "time_created": "2026-01-29T17:11:52Z"
}
The current rate limit is 400 requests per second per endpoint. This threshold is subject to change. To avoid hitting rate limits:
  • Batch requests where possible rather than making many individual calls in quick succession.
  • Implement exponential backoff — when you receive a 429 response, wait before retrying and progressively increase the delay between subsequent retries.
Do not retry 429 responses immediately or in a tight loop. Doing so will extend the time your requests are throttled.