Skip to main content
Codes in the 4xx and 5xx range indicate that folk’s API denied the request. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with folk’s servers. For 2xx responses, see Success responses.

Error response

The error response contains a single error object that includes the following properties:
  • code: The code that identifies the error.
  • message: A human-readable description of the error.
  • documentationUrl: An URL to the documentation that describes the error.
  • timestamp: The timestamp when the error occurred.
  • requestId: The request identifier.
Some 4xx errors that could be handled programmatically (e.g., validation errors) include a details property that provides more information about the error. Refer to each specific error in order to see if a details property is available and its shape.

Error list

The errors that could be returned by folk’s API are the following:

Bad request

Status code: 400
The request was malformed or invalid.
It is also returned with the IDEMPOTENCY_KEY_INVALID code when the Idempotency-Key header is malformed. See the idempotency section.

Unauthorized

Status code: 401
Access to the resource is unauthorized.
This error is usually returned when the API key is invalid or not provided. Always make sure to provide an API key in the Authorization header.
Read more about authentication in the authentication section.

Payment required

Status code: 402
The workspace doesn’t have enough credits to perform the request.
This error is returned by operations that consume credits, such as enrichments, when the workspace doesn’t have enough credits left. Nothing is performed or charged: add credits to the workspace, or send a smaller request. Launching a campaign beyond the messages of the plan answers 402 with the code MESSAGE_LIMIT_REACHED, and the plan’s limit in details. A campaign whose follow-ups need sequences that the plan doesn’t include answers SEQUENCES_NOT_AVAILABLE.

Forbidden

Status code: 403
Access to the resource is forbidden.
This error is usually returned when the API key doesn’t have permissions to perform the operation. Writing or launching a campaign with a sender you can’t send from answers the code SENDER_NOT_ALLOWED, with the step in details.step when the sender is that of a step.

Not found

Status code: 404
The requested resource was not found.
This error is usually returned when a resource that is being requested doesn’t exist.

Conflict

Status code: 409
A request with the same Idempotency-Key is still being processed, or the resource is in a state that does not allow the operation.
The code says which conflict happened, for example CAMPAIGN_NOT_EDITABLE when editing a campaign that is no longer a draft, CAMPAIGN_STATUS_CONFLICT when reviewing a campaign that is not a draft, or CAMPAIGN_NOT_STOPPABLE when stopping a campaign that was never launched. When the conflict resolves on its own, such as CAMPAIGN_PROCESSING while a campaign generates its messages, the response has a Retry-After header with the number of seconds to wait before retrying. For an Idempotency-Key conflict, retry the request once the first one has completed. Read more in the idempotency section.

Payload too large

Status code: 413
The request body is larger than the operation accepts: 500 KB.
To create a campaign with more messages, send fewer messages and edit the rest once the campaign is in review, with the batch update of its messages.

Unsupported media type

Status code: 415
The request body is not JSON: send it with the Content-Type: application/json header.

Unprocessable entity

Status code: 422
The request contains invalid data.
This error is usually returned when there is a validation error in the body or query parameters of the request. It is also returned with the IDEMPOTENCY_KEY_REUSED code when an Idempotency-Key is reused for a different request, and with the IDEMPOTENCY_RESPONSE_NOT_STORED code when a retried request already ran but its response could not be saved, because it was too large or not JSON text. See the idempotency section. The details object includes an array of issues describing each validation rule that has failed validation. You can find an exaustive list of all available properties on the official Zod documentation.

Rate limiting

Status code: 429
A rate limit policy has been exceeded.
The details object describes the policy that was exceeded. When several policies are exceeded, it describes the one that resets last. It includes the following properties:
  • policy: The name of the exceeded policy: default or burst.
  • limit: The maximum number of requests allowed per window by this policy.
  • remaining: The number of requests remaining in the current window. Always 0 for the exceeded policy.
  • windowSeconds: The length of the policy’s window, in seconds.
  • retryAfter: The ISO 8601 Datetime when the policy’s window resets and you can retry.
  • policies: The status of every policy applied to the request, each with the same properties as above.
Read more about rate limits in the rate limits section. Launching a campaign beyond the daily quota of its Gmail sender also answers 429, with the code SENDER_QUOTA_EXCEEDED and details holding step, usedQuota and totalQuota. Retry the next day, or send from another sender.

Internal server error

Status code: 500
An error occurred on the server.
If this error is returned, it means folk’s servers encountered an error while processing the request.
If the error persists, please contact support and include the requestId shown in the response.

Service unavailable

Status code: 503
The service is temporarily unavailable.
If this error is returned, it means folk’s servers are temporarily unavailable.
folk strives to keep the service available at all times, but sometimes it’s necessary to perform maintenance or upgrades.
If the error persists, please contact support and include the requestId shown in the response. It is also returned with the IDEMPOTENCY_UNAVAILABLE code when folk cannot guarantee idempotency for a request sent with an Idempotency-Key. The request was not processed: retry it with the same key. See the idempotency section.