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 singleerror 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.
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:400The 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:401Access 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:402The 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:403Access 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:404The requested resource was not found. This error is usually returned when a resource that is being requested doesn’t exist.
Conflict
Status code:409A 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:413The 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:415The request body is not JSON: send it with the
Content-Type: application/json header.
Unprocessable entity
Status code:422The 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:429A 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:defaultorburst.limit: The maximum number of requests allowed per window by this policy.remaining: The number of requests remaining in the current window. Always0for 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.
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:500An 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:503The 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.