Appnigma
SDKReference

Last updated on October 23, 2026

Errors

Tell failures apart by error class and code, and know what to do about each one.

Every error

Every failure is an error you can catch by class. Every error carries code, message, status and the request id: requestId in TypeScript, request_id in Ruby and Python.

All of them extend one base class, so one check catches anything from Appnigma: SdkError in TypeScript, Appnigma::Error in Ruby, AppnigmaError in Python.

Tip

Quote the request id when you write to support@appnigma.ai. Never include your key or a token.

The classes

TypeScriptRubyPythonWhenExtra field
SdkInputErrorAppnigma::InputErrorInputError400. A field is wrong or missing. Also raised before any call for a bad setting or a bad end customer id.problems, a list of { field, problem }
SdkAuthErrorAppnigma::AuthErrorAuthError401 or 403. The key is missing, unknown or cancelled, the microserver is not enabled, the platform is not switched on for you, or the connection lacks a scope an action needs. Also raised when a client starts with no key.
SdkNotFoundErrorAppnigma::NotFoundErrorNotFoundError404. No connection for that end customer on that platform, no such function, no such action, or no such record. When the function exists on another platform, details.platforms names it.
SdkReconnectErrorAppnigma::ReconnectErrorReconnectError409 with CONNECTION_NEEDS_RECONNECT. The end customer has to approve again.
SdkNotAvailableErrorAppnigma::NotAvailableErrorNotAvailableErrorAny other 409. The platform has no unified data for that yet; use request.
SdkRetiredErrorAppnigma::RetiredErrorRetiredError410 with FUNCTION_RETIRED. The function was live and was removed from your logic; it will not answer again.
SdkRateLimitErrorAppnigma::RateLimitErrorRateLimitError429, after the retries. Too many calls, or the platform asked us to slow down.The wait in seconds, or empty when the server named none: retryAfterSeconds in TypeScript, retry_after_seconds in Ruby and Python
SdkServerErrorAppnigma::ServerErrorServerErrorAny 5xx, after the retries. Also any answer that is not JSON.
SdkNetworkErrorAppnigma::NetworkErrorNetworkErrorThe API could not be reached, or an attempt ran out of time, after the retries. status and the request id are empty.The underlying error: cause in TypeScript and Ruby, __cause__ in Python

Catch by class

try {
  await appnigma.post({ endCustomerId: "lawfirm-123", platform: "hubspot", object: "contact", record: {} });
} catch (error) {
  if (error instanceof SdkInputError) {
    for (const problem of error.problems) console.log(problem.field, problem.problem);
  } else if (error instanceof SdkAuthError) {
    console.log("check the key", error.code);
  } else if (error instanceof SdkNotFoundError) {
    console.log("this end customer is not connected yet");
  } else if (error instanceof SdkReconnectError) {
    console.log("ask the end customer to connect again");
  } else if (error instanceof SdkRateLimitError) {
    console.log("wait", error.retryAfterSeconds, "seconds");
  } else if (error instanceof SdkServerError) {
    console.log("our side failed, quote this id to support:", error.requestId);
  } else if (error instanceof SdkNetworkError) {
    console.log("could not reach the API", error.cause);
  } else {
    throw error;
  }
}
begin
  client.post(end_customer_id: "lawfirm-123", platform: "hubspot", object: "contact", record: {})
rescue Appnigma::InputError => e
  e.problems.each { |problem| puts "#{problem[:field]} #{problem[:problem]}" }
rescue Appnigma::AuthError => e
  puts "check the key: #{e.code}"
rescue Appnigma::NotFoundError
  puts "this end customer is not connected yet"
rescue Appnigma::ReconnectError
  puts "ask the end customer to connect again"
rescue Appnigma::RateLimitError => e
  puts "wait #{e.retry_after_seconds} seconds"
rescue Appnigma::ServerError => e
  puts "our side failed, quote this id to support: #{e.request_id}"
rescue Appnigma::NetworkError => e
  puts "could not reach the API: #{e.cause&.message}"
end
from appnigma import (
    AuthError,
    InputError,
    NetworkError,
    NotFoundError,
    RateLimitError,
    ReconnectError,
    ServerError,
)

try:
    client.post(end_customer_id="lawfirm-123", platform="hubspot", object="contact", record={})
except InputError as error:
    for problem in error.problems:
        print(problem["field"], problem["problem"])
except AuthError as error:
    print("check the key:", error.code)
except NotFoundError:
    print("this end customer is not connected yet")
except ReconnectError:
    print("ask the end customer to connect again")
except RateLimitError as error:
    print(f"wait {error.retry_after_seconds} seconds")
except ServerError as error:
    print("our side failed, quote this id to support:", error.request_id)
except NetworkError as error:
    print("could not reach the API:", error.__cause__)

Or catch the base class:

try {
  await appnigma.connections.get({ endCustomerId: "nobody-here", platform: "hubspot" });
} catch (error) {
  if (error instanceof SdkError) {
    console.log(error.name, error.code, error.status, error.requestId);
  } else {
    throw error;
  }
}
begin
  client.connections.get(end_customer_id: "nobody-here", platform: "hubspot")
rescue Appnigma::Error => e
  puts "#{e.class} #{e.code} #{e.status} #{e.request_id}"
end
from appnigma import AppnigmaError

try:
    client.connections.get(end_customer_id="nobody-here", platform="hubspot")
except AppnigmaError as error:
    print(type(error).__name__, error.code, error.status, error.request_id)

Every code

code is one of the codes below, or whatever a newer server sent. A code your version of the SDK does not know is kept as it is, never replaced. The full list is in SDK_ERROR_CODES in TypeScript, Appnigma::ERROR_CODES in Ruby and appnigma.ERROR_CODES in Python.

StatusCodeWhenWhat to do
400INVALID_INPUTA field is wrong, missing or unknown. problems lists each one.Fix the fields it names.
401SDK_KEY_MISSINGNo key was sent.Set APPNIGMA_SDK_KEY, or pass the key.
401SDK_KEY_INVALIDThe key is unknown.Check the key. Ask Appnigma for a new one if needed.
401SDK_KEY_CANCELLEDThe key was cancelled.Ask Appnigma for a new key.
403MICROSERVER_NOT_ENABLEDYour company has no active microserver.Contact Appnigma.
403PLATFORM_NOT_ENABLEDThe platform is not switched on for your company.Ask Appnigma to switch it on.
403MISSING_SCOPESThe end customer's connection was not given a scope an action needs. details.missing names them.The connection needs those scopes before the action can run.
404END_CUSTOMER_NOT_FOUNDNo connection for that end customer on that platform.Connect the end customer.
404FUNCTION_NOT_FOUNDNo function with that platform and name. details.platforms names another platform that has it.Check the name and platform with catalog.
404ACTION_NOT_FOUNDThe platform has no action with that name.Check the name with actions.list.
404RECORD_NOT_FOUNDNo record with that id.Check the id.
409CONNECTION_NEEDS_RECONNECTThe end customer has to approve again.Send them a new connect link.
409DATA_TYPE_NOT_AVAILABLEThe platform has no unified data for that yet.Use request.
410FUNCTION_RETIREDThe function was live and was removed from your logic. details name the function and when it was retired.Stop calling it. Check what is live with catalog.
429RATE_LIMITEDToo many calls with this key.Wait as long as the error says, then try again.
429PLATFORM_RATE_LIMITEDThe platform asked us to slow down.Wait as long as the error says, then try again.
502PLATFORM_ERRORThe platform refused the call. message carries its reason.Read the message.
504TIMED_OUTThe function did not answer in time.Decide whether to call again.
500LOGIC_FAILEDThe function failed. No inner detail is returned.Quote the request id to support.
500INTERNAL_ERRORSomething went wrong on Appnigma's side.Quote the request id to support.

On this page